<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow: detail/doc/doc-coding_style.cpp Source File</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow<span id="projectnumber">&#160;2.0.0</span>
   </div>
   <div id="projectbrief">Flow project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="dir_12ed47f6ecc03f411f952cdaf2e983c4.html">detail</a></li><li class="navelem"><a class="el" href="dir_fc8890094717abd5fd945eea3218f11d.html">doc</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="headertitle"><div class="title">doc-coding_style.cpp</div></div>
</div><!--header-->
<div class="contents">
<a href="doc-coding__style_8cpp.html">Go to the documentation of this file.</a><div class="fragment"><div class="line"><a id="l00001" name="l00001"></a><span class="lineno">    1</span><span class="comment">/* Flow</span></div>
<div class="line"><a id="l00002" name="l00002"></a><span class="lineno">    2</span><span class="comment"> * Copyright 2023 Akamai Technologies, Inc.</span></div>
<div class="line"><a id="l00003" name="l00003"></a><span class="lineno">    3</span><span class="comment"> *</span></div>
<div class="line"><a id="l00004" name="l00004"></a><span class="lineno">    4</span><span class="comment"> * Licensed under the Apache License, Version 2.0 (the</span></div>
<div class="line"><a id="l00005" name="l00005"></a><span class="lineno">    5</span><span class="comment"> * &quot;License&quot;); you may not use this file except in</span></div>
<div class="line"><a id="l00006" name="l00006"></a><span class="lineno">    6</span><span class="comment"> * compliance with the License.  You may obtain a copy</span></div>
<div class="line"><a id="l00007" name="l00007"></a><span class="lineno">    7</span><span class="comment"> * of the License at</span></div>
<div class="line"><a id="l00008" name="l00008"></a><span class="lineno">    8</span><span class="comment"> *</span></div>
<div class="line"><a id="l00009" name="l00009"></a><span class="lineno">    9</span><span class="comment"> *   https://www.apache.org/licenses/LICENSE-2.0</span></div>
<div class="line"><a id="l00010" name="l00010"></a><span class="lineno">   10</span><span class="comment"> *</span></div>
<div class="line"><a id="l00011" name="l00011"></a><span class="lineno">   11</span><span class="comment"> * Unless required by applicable law or agreed to in</span></div>
<div class="line"><a id="l00012" name="l00012"></a><span class="lineno">   12</span><span class="comment"> * writing, software distributed under the License is</span></div>
<div class="line"><a id="l00013" name="l00013"></a><span class="lineno">   13</span><span class="comment"> * distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR</span></div>
<div class="line"><a id="l00014" name="l00014"></a><span class="lineno">   14</span><span class="comment"> * CONDITIONS OF ANY KIND, either express or implied.</span></div>
<div class="line"><a id="l00015" name="l00015"></a><span class="lineno">   15</span><span class="comment"> * See the License for the specific language governing</span></div>
<div class="line"><a id="l00016" name="l00016"></a><span class="lineno">   16</span><span class="comment"> * permissions and limitations under the License. */</span></div>
<div class="line"><a id="l00017" name="l00017"></a><span class="lineno">   17</span><span class="comment"></span> </div>
<div class="line"><a id="l00018" name="l00018"></a><span class="lineno">   18</span><span class="comment">/**</span></div>
<div class="line"><a id="l00019" name="l00019"></a><span class="lineno">   19</span><span class="comment"> * @file</span></div>
<div class="line"><a id="l00020" name="l00020"></a><span class="lineno">   20</span><span class="comment"> *</span></div>
<div class="line"><a id="l00021" name="l00021"></a><span class="lineno">   21</span><span class="comment"> * Doc file (meant for reading, not compiling) that formally defines the coding style for the rest of the project.</span></div>
<div class="line"><a id="l00022" name="l00022"></a><span class="lineno">   22</span><span class="comment"> *</span></div>
<div class="line"><a id="l00023" name="l00023"></a><span class="lineno">   23</span><span class="comment"> * @todo There are a few little to-dos inside the Doxygen-skipped main body of doc-coding_style.cpp; check them out.</span></div>
<div class="line"><a id="l00024" name="l00024"></a><span class="lineno">   24</span><span class="comment"> *</span></div>
<div class="line"><a id="l00025" name="l00025"></a><span class="lineno">   25</span><span class="comment"> * @todo A script/tool/something that would auto-scan the code for violations of cosmetic conventions described</span></div>
<div class="line"><a id="l00026" name="l00026"></a><span class="lineno">   26</span><span class="comment"> * in doc-coding_style.cpp.  It need not be perfect or comprehensive.  Humans tend to have difficulty following lots</span></div>
<div class="line"><a id="l00027" name="l00027"></a><span class="lineno">   27</span><span class="comment"> * of conventions, and it then clutters up code reviews subsequently.</span></div>
<div class="line"><a id="l00028" name="l00028"></a><span class="lineno">   28</span><span class="comment"> *</span></div>
<div class="line"><a id="l00029" name="l00029"></a><span class="lineno">   29</span><span class="comment"> * @todo In all of Flow, scan for the unintentional use of the period character in auto-brief summaries in many doc</span></div>
<div class="line"><a id="l00030" name="l00030"></a><span class="lineno">   30</span><span class="comment"> * headers.  A period will be assumed to be the end of the brief summary.  We&#39;ve been disciplined about this, but</span></div>
<div class="line"><a id="l00031" name="l00031"></a><span class="lineno">   31</span><span class="comment"> * I (ygoldfel) just realized that, e.g., &quot;boost.asio&quot; has a period and yet is present in at least some doc headers.</span></div>
<div class="line"><a id="l00032" name="l00032"></a><span class="lineno">   32</span><span class="comment"> * Fix those in some consistent yet palatable way, so that the Doxygen output for those isn&#39;t prematurely truncated.</span></div>
<div class="line"><a id="l00033" name="l00033"></a><span class="lineno">   33</span><span class="comment"> * (Check that Doxygen isn&#39;t smart enough to figure it out already.  If it is, delete this to-do.)</span></div>
<div class="line"><a id="l00034" name="l00034"></a><span class="lineno">   34</span><span class="comment"> */</span></div>
<div class="line"><a id="l00035" name="l00035"></a><span class="lineno">   35</span> </div>
<div class="line"><a id="l00036" name="l00036"></a><span class="lineno">   36</span><span class="comment">/* This is basically `#if 0` but fools most syntax highlighters to still treat the body as active C++ to highlight.</span></div>
<div class="line"><a id="l00037" name="l00037"></a><span class="lineno">   37</span><span class="comment"> * `#if 0` often leads to annoying graying out.  Also this ensures Doxygen doesn&#39;t try to scan it for documentation</span></div>
<div class="line"><a id="l00038" name="l00038"></a><span class="lineno">   38</span><span class="comment"> * to generate.  This file is meant to be read straight up (if ideally with syntax highlighting). */</span></div>
<div class="line"><a id="l00039" name="l00039"></a><span class="lineno">   39</span><span class="preprocessor">#ifndef FLOW_DOXYGEN_ONLY</span></div>
<div class="line"><a id="l00040" name="l00040"></a><span class="lineno">   40</span><span class="preprocessor">#  ifdef FLOW_DOXYGEN_ONLY</span></div>
<div class="line"><a id="l00041" name="l00041"></a><span class="lineno">   41</span> </div>
<div class="line"><a id="l00042" name="l00042"></a><span class="lineno">   42</span><span class="comment">// -- Synopsis / Table of Contents --</span></div>
<div class="line"><a id="l00043" name="l00043"></a><span class="lineno">   43</span> </div>
<div class="line"><a id="l00044" name="l00044"></a><span class="lineno">   44</span><span class="comment">/* - About</span></div>
<div class="line"><a id="l00045" name="l00045"></a><span class="lineno">   45</span><span class="comment"> * - Style guide [cosmetic, objective, fairly exhaustive]</span></div>
<div class="line"><a id="l00046" name="l00046"></a><span class="lineno">   46</span><span class="comment"> *   - Folder level, namespace basics</span></div>
<div class="line"><a id="l00047" name="l00047"></a><span class="lineno">   47</span><span class="comment"> *   - File level</span></div>
<div class="line"><a id="l00048" name="l00048"></a><span class="lineno">   48</span><span class="comment"> *   - Basics: Line width; indent; comments; doc header basics</span></div>
<div class="line"><a id="l00049" name="l00049"></a><span class="lineno">   49</span><span class="comment"> *   - Identifier formatting</span></div>
<div class="line"><a id="l00050" name="l00050"></a><span class="lineno">   50</span><span class="comment"> *   - Order of declarations</span></div>
<div class="line"><a id="l00051" name="l00051"></a><span class="lineno">   51</span><span class="comment"> *   - Spacing and indentation</span></div>
<div class="line"><a id="l00052" name="l00052"></a><span class="lineno">   52</span><span class="comment"> *   - Misc/loose ends</span></div>
<div class="line"><a id="l00053" name="l00053"></a><span class="lineno">   53</span><span class="comment"> *   - Header files and forwarding; _fwd.hpp pattern</span></div>
<div class="line"><a id="l00054" name="l00054"></a><span class="lineno">   54</span><span class="comment"> *     - Exceptions to _fwd.hpp pattern</span></div>
<div class="line"><a id="l00055" name="l00055"></a><span class="lineno">   55</span><span class="comment"> *     - _fwd.hpp pattern odds/ends: Macros, constexpr globals</span></div>
<div class="line"><a id="l00056" name="l00056"></a><span class="lineno">   56</span><span class="comment"> * - Best practices [conceptual, subjective, non-exhaustive]</span></div>
<div class="line"><a id="l00057" name="l00057"></a><span class="lineno">   57</span><span class="comment"> *   - Comments</span></div>
<div class="line"><a id="l00058" name="l00058"></a><span class="lineno">   58</span><span class="comment"> *   - Inlining</span></div>
<div class="line"><a id="l00059" name="l00059"></a><span class="lineno">   59</span><span class="comment"> *   - Doxygen doc header deep-dive</span></div>
<div class="line"><a id="l00060" name="l00060"></a><span class="lineno">   60</span><span class="comment"> *   - Namespaces, libraries</span></div>
<div class="line"><a id="l00061" name="l00061"></a><span class="lineno">   61</span><span class="comment"> *   - Error handling</span></div>
<div class="line"><a id="l00062" name="l00062"></a><span class="lineno">   62</span><span class="comment"> *   - Logging</span></div>
<div class="line"><a id="l00063" name="l00063"></a><span class="lineno">   63</span><span class="comment"> *   - Types and type safety</span></div>
<div class="line"><a id="l00064" name="l00064"></a><span class="lineno">   64</span><span class="comment"> *   - General design do&#39;s and don&#39;ts */</span></div>
<div class="line"><a id="l00065" name="l00065"></a><span class="lineno">   65</span> </div>
<div class="line"><a id="l00066" name="l00066"></a><span class="lineno">   66</span><span class="comment">// -- About --</span></div>
<div class="line"><a id="l00067" name="l00067"></a><span class="lineno">   67</span> </div>
<div class="line"><a id="l00068" name="l00068"></a><span class="lineno">   68</span><span class="comment">/* This source file is meant to be read by all coders of Flow (not coders *using* Flow).  Do not compile it.</span></div>
<div class="line"><a id="l00069" name="l00069"></a><span class="lineno">   69</span><span class="comment"> * It aims to answer the question: What is the formal style for Flow code (API and internals)?  The answer is *slightly*</span></div>
<div class="line"><a id="l00070" name="l00070"></a><span class="lineno">   70</span><span class="comment"> * subtle.  The coding style is formally as follows:</span></div>
<div class="line"><a id="l00071" name="l00071"></a><span class="lineno">   71</span><span class="comment"> *   - The rules in this file are to be followed, unless there is an excellent, rare reason not to.</span></div>
<div class="line"><a id="l00072" name="l00072"></a><span class="lineno">   72</span><span class="comment"> *     - Many rules are not given as explicit rules but by example.  E.g., if a code snippet formats a `static`</span></div>
<div class="line"><a id="l00073" name="l00073"></a><span class="lineno">   73</span><span class="comment"> *       non-member variable with certain formatting and doc header in this file, then that is to be taken as an</span></div>
<div class="line"><a id="l00074" name="l00074"></a><span class="lineno">   74</span><span class="comment"> *       rule that that is how such declarations are to be done.</span></div>
<div class="line"><a id="l00075" name="l00075"></a><span class="lineno">   75</span><span class="comment"> *     - Either way, following these rules helps *consistency* as well as hopefully clarity, maintainability, etc.</span></div>
<div class="line"><a id="l00076" name="l00076"></a><span class="lineno">   76</span><span class="comment"> *   - If some situation is not specified in this file (either as an explicit rule or by example), and the coder is</span></div>
<div class="line"><a id="l00077" name="l00077"></a><span class="lineno">   77</span><span class="comment"> *     asking oneself what this means about how one should proceed, then these are the possibilities:</span></div>
<div class="line"><a id="l00078" name="l00078"></a><span class="lineno">   78</span><span class="comment"> *     -# There is no convention to follow.  Coder should do what they want while being guided by personal dedication</span></div>
<div class="line"><a id="l00079" name="l00079"></a><span class="lineno">   79</span><span class="comment"> *        to clarity, maintainaibility, etc.  All that will be lacking, then, is potentially *consistency* with what</span></div>
<div class="line"><a id="l00080" name="l00080"></a><span class="lineno">   80</span><span class="comment"> *        some other code snippet did in that situation.</span></div>
<div class="line"><a id="l00081" name="l00081"></a><span class="lineno">   81</span><span class="comment"> *        - This certainly happens, but it is worth a little effort to push for consistency and attempt the following</span></div>
<div class="line"><a id="l00082" name="l00082"></a><span class="lineno">   82</span><span class="comment"> *          bullet point instead.  If that fails, OK, come back here.</span></div>
<div class="line"><a id="l00083" name="l00083"></a><span class="lineno">   83</span><span class="comment"> *     -# There is a convention to follow, though not in the present file.  Check existing Flow code for how it tends</span></div>
<div class="line"><a id="l00084" name="l00084"></a><span class="lineno">   84</span><span class="comment"> *        to be done.  If there&#39;s a clear answer, copy that.</span></div>
<div class="line"><a id="l00085" name="l00085"></a><span class="lineno">   85</span><span class="comment"> *        - In addition, if it appears to be an ironclad 95%+ convention in practice, add it to the present style</span></div>
<div class="line"><a id="l00086" name="l00086"></a><span class="lineno">   86</span><span class="comment"> *          doc to eliminate the ambiguity next time.</span></div>
<div class="line"><a id="l00087" name="l00087"></a><span class="lineno">   87</span><span class="comment"> *</span></div>
<div class="line"><a id="l00088" name="l00088"></a><span class="lineno">   88</span><span class="comment"> * Flow is extremely consistent and places a high value on aesthetics, clarity, maintainability, and documentation.</span></div>
<div class="line"><a id="l00089" name="l00089"></a><span class="lineno">   89</span><span class="comment"> * Because it was originally written by one person and with an emphasis on these, it&#39;s in a relatively rare state for</span></div>
<div class="line"><a id="l00090" name="l00090"></a><span class="lineno">   90</span><span class="comment"> * a code base of this size: Good style with near-100% consistency is actually achieved.  So, let&#39;s keep achieving it</span></div>
<div class="line"><a id="l00091" name="l00091"></a><span class="lineno">   91</span><span class="comment"> * in inductive fashion, so to speak.</span></div>
<div class="line"><a id="l00092" name="l00092"></a><span class="lineno">   92</span><span class="comment"> *</span></div>
<div class="line"><a id="l00093" name="l00093"></a><span class="lineno">   93</span><span class="comment"> * Really, it is quite realistic to accomplish this by simply following the rule,</span></div>
<div class="line"><a id="l00094" name="l00094"></a><span class="lineno">   94</span><span class="comment"> * &quot;if in doubt how to present some code, (1) it matters what you decide, and (2) use existing Flow code to guide</span></div>
<div class="line"><a id="l00095" name="l00095"></a><span class="lineno">   95</span><span class="comment"> * you by example.&quot;  Hence the present file is not *necessary*; or it could contain nothing but the present commentary</span></div>
<div class="line"><a id="l00096" name="l00096"></a><span class="lineno">   96</span><span class="comment"> * and nothing else.  Hence the following snippets and comments exist for *convenience* only: so that one can easily</span></div>
<div class="line"><a id="l00097" name="l00097"></a><span class="lineno">   97</span><span class="comment"> * pop on over to here and most times find the desired convention/rule (as opposed to fishing around the existing</span></div>
<div class="line"><a id="l00098" name="l00098"></a><span class="lineno">   98</span><span class="comment"> * code base).</span></div>
<div class="line"><a id="l00099" name="l00099"></a><span class="lineno">   99</span><span class="comment"> *</span></div>
<div class="line"><a id="l00100" name="l00100"></a><span class="lineno">  100</span><span class="comment"> * The rest is split up into 2 groups of guidelines.</span></div>
<div class="line"><a id="l00101" name="l00101"></a><span class="lineno">  101</span><span class="comment"> *  - STYLE GUIDE: These are cosmetic rules.  They&#39;re fairly objective, and to achieve consistency one must follow</span></div>
<div class="line"><a id="l00102" name="l00102"></a><span class="lineno">  102</span><span class="comment"> *    them (unless excellent reason to not).  Basically this is, like, indentation and ordering and formatting, etc.</span></div>
<div class="line"><a id="l00103" name="l00103"></a><span class="lineno">  103</span><span class="comment"> *  - BEST PRACTICES: These are subjective coding style rules.  The aim here is no longer mere cosmetic consistency</span></div>
<div class="line"><a id="l00104" name="l00104"></a><span class="lineno">  104</span><span class="comment"> *    but the more subjective goals of readability, maintainability, and elegance.  These are things like: avoid</span></div>
<div class="line"><a id="l00105" name="l00105"></a><span class="lineno">  105</span><span class="comment"> *    `protected` non-`const` data members; prefer iteration to massive recursion; etc. */</span></div>
<div class="line"><a id="l00106" name="l00106"></a><span class="lineno">  106</span> </div>
<div class="line"><a id="l00107" name="l00107"></a><span class="lineno">  107</span><span class="comment">// -- STYLE GUIDE: Folder level, namespace basics --</span></div>
<div class="line"><a id="l00108" name="l00108"></a><span class="lineno">  108</span> </div>
<div class="line"><a id="l00109" name="l00109"></a><span class="lineno">  109</span><span class="comment">/* For *all* code under `flow` -- even though (as noted in common.hpp) the various namespaces are orthogonal to each</span></div>
<div class="line"><a id="l00110" name="l00110"></a><span class="lineno">  110</span><span class="comment"> * other in functionality -- the following conventions apply.  We basically use similar conventions to Boost and</span></div>
<div class="line"><a id="l00111" name="l00111"></a><span class="lineno">  111</span><span class="comment"> * all/most popular STL implementations, plus some additional conventions.  To wit:</span></div>
<div class="line"><a id="l00112" name="l00112"></a><span class="lineno">  112</span><span class="comment"> *</span></div>
<div class="line"><a id="l00113" name="l00113"></a><span class="lineno">  113</span><span class="comment"> *   - There is a (nearly) 1-to-1 relationship between the tree of `namespace`s and the directory tree.</span></div>
<div class="line"><a id="l00114" name="l00114"></a><span class="lineno">  114</span><span class="comment"> *     That is: `flow` is the top level directory and `namespace`; within it are directories X1, X2, ..., each of which</span></div>
<div class="line"><a id="l00115" name="l00115"></a><span class="lineno">  115</span><span class="comment"> *     is 1-to-1 to `namespace`s X1, X2, ....  This pattern continues recursively as well.</span></div>
<div class="line"><a id="l00116" name="l00116"></a><span class="lineno">  116</span><span class="comment"> *     - A potential exception to this is that it may make sense to create a sub-directory, even if doesn&#39;t have a</span></div>
<div class="line"><a id="l00117" name="l00117"></a><span class="lineno">  117</span><span class="comment"> *       corresponding namespace, from time to time, for special organizational purposes.</span></div>
<div class="line"><a id="l00118" name="l00118"></a><span class="lineno">  118</span><span class="comment"> *     - Conversely, a potential exception is namespace X has sub-namespace Y, yet there is no X/Y directory</span></div>
<div class="line"><a id="l00119" name="l00119"></a><span class="lineno">  119</span><span class="comment"> *       for stuff from `Y`.  We generally recommend against this, except when all of the stuff in `namespace Y`</span></div>
<div class="line"><a id="l00120" name="l00120"></a><span class="lineno">  120</span><span class="comment"> *       can be declared in a very small number of headers... namely at most Y.hpp and/or Y_fwd.hpp.</span></div>
<div class="line"><a id="l00121" name="l00121"></a><span class="lineno">  121</span><span class="comment"> *     - Since macros (which we generally avoid except where necessary, usually for logging only) do not reside in</span></div>
<div class="line"><a id="l00122" name="l00122"></a><span class="lineno">  122</span><span class="comment"> *       `namespace`s, we simulate &quot;macro namespaces&quot; via prefixes.  See elsewhere in the present file for details.</span></div>
<div class="line"><a id="l00123" name="l00123"></a><span class="lineno">  123</span><span class="comment"> *   - Suppose flow/A/B is a directory corresponding to namespace `flow::A::B`.  Then any file of form flow/A/B/x.hpp</span></div>
<div class="line"><a id="l00124" name="l00124"></a><span class="lineno">  124</span><span class="comment"> *     must contain *only* symbols in `flow::A::B` *that are intended to be publicly available*.  (Of course, function</span></div>
<div class="line"><a id="l00125" name="l00125"></a><span class="lineno">  125</span><span class="comment"> *     bodies -- notably function templates -- must sometimes also reside in header files, alongside the interface.)</span></div>
<div class="line"><a id="l00126" name="l00126"></a><span class="lineno">  126</span><span class="comment"> *     - Symbols necessary to implement anything else in flow/A/B, but that are *not* intended for public use, must</span></div>
<div class="line"><a id="l00127" name="l00127"></a><span class="lineno">  127</span><span class="comment"> *       reside in flow/A/B/detail.</span></div>
<div class="line"><a id="l00128" name="l00128"></a><span class="lineno">  128</span><span class="comment"> *       - The user is explicitly not allowed to `include` them directly.  However this is not enforced and not</span></div>
<div class="line"><a id="l00129" name="l00129"></a><span class="lineno">  129</span><span class="comment"> *         enforceable.  (Note: The same is true of all STLs, Boost, and many other products.)  (A public header</span></div>
<div class="line"><a id="l00130" name="l00130"></a><span class="lineno">  130</span><span class="comment"> *         *may* include a detail/ header if needed, such as when implementing function templates at times;</span></div>
<div class="line"><a id="l00131" name="l00131"></a><span class="lineno">  131</span><span class="comment"> *         however the user is by convention not allowed to directly include them.)</span></div>
<div class="line"><a id="l00132" name="l00132"></a><span class="lineno">  132</span><span class="comment"> *       - Similarly, the user is explicitly disallowed to reference such symbols directly.  Again, this isn&#39;t enforced</span></div>
<div class="line"><a id="l00133" name="l00133"></a><span class="lineno">  133</span><span class="comment"> *         or (in many cases) enforceable.</span></div>
<div class="line"><a id="l00134" name="l00134"></a><span class="lineno">  134</span><span class="comment"> *       - At this time we do not require (or encourage) to segregate such non-public symbols in</span></div>
<div class="line"><a id="l00135" name="l00135"></a><span class="lineno">  135</span><span class="comment"> *         `detail` sub-`namespace`s.  (Boost/STL sometimes does this; sometimes does not.)  Reason is it&#39;s annoying to</span></div>
<div class="line"><a id="l00136" name="l00136"></a><span class="lineno">  136</span><span class="comment"> *         move stuff between namespaces when making a non-public API public or vice versa; since user isn&#39;t meant</span></div>
<div class="line"><a id="l00137" name="l00137"></a><span class="lineno">  137</span><span class="comment"> *         to use such things regardless, it is sufficient to merely *indicate* what is public and what isn&#39;t; for this</span></div>
<div class="line"><a id="l00138" name="l00138"></a><span class="lineno">  138</span><span class="comment"> *         the choice of file/directory is sufficient and no actual `namespace` is required.  We may change this policy.</span></div>
<div class="line"><a id="l00139" name="l00139"></a><span class="lineno">  139</span><span class="comment"> *     - However: It is typical that a file of form x.hpp requires an x.cpp counterpart.  Obviously, this would not</span></div>
<div class="line"><a id="l00140" name="l00140"></a><span class="lineno">  140</span><span class="comment"> *       be exported into any public `include/` directory (as it is not a header file).  The rule is x.cpp is to be</span></div>
<div class="line"><a id="l00141" name="l00141"></a><span class="lineno">  141</span><span class="comment"> *       in the same directory as x.hpp (alongside it).</span></div>
<div class="line"><a id="l00142" name="l00142"></a><span class="lineno">  142</span><span class="comment"> *       - In the rare case where a file z.cpp does not have a z.hpp</span></div>
<div class="line"><a id="l00143" name="l00143"></a><span class="lineno">  143</span><span class="comment"> *         counterpart, z.cpp should usually reside under detail/ after all.  Sometimes it might make sense to place</span></div>
<div class="line"><a id="l00144" name="l00144"></a><span class="lineno">  144</span><span class="comment"> *         it near its most-related .hpp file.  This particular decision is left to</span></div>
<div class="line"><a id="l00145" name="l00145"></a><span class="lineno">  145</span><span class="comment"> *         be made on a case-by-case basis however and shouldn&#39;t come up very often.  It is also of (relatively) low</span></div>
<div class="line"><a id="l00146" name="l00146"></a><span class="lineno">  146</span><span class="comment"> *         importance, as .cpp files are not part of the exported API.</span></div>
<div class="line"><a id="l00147" name="l00147"></a><span class="lineno">  147</span><span class="comment"> *   - Headers must end in .hpp.  Others must end in .cpp.  In the rare case of a C-language-user-supporting header, use</span></div>
<div class="line"><a id="l00148" name="l00148"></a><span class="lineno">  148</span><span class="comment"> *     .h.  At this time we don&#39;t use .inl (and similar) files, but if there&#39;s a good reason we might do so, in which</span></div>
<div class="line"><a id="l00149" name="l00149"></a><span class="lineno">  149</span><span class="comment"> *     case the convention should be clearly described here.</span></div>
<div class="line"><a id="l00150" name="l00150"></a><span class="lineno">  150</span><span class="comment"> *   - Do not use redundant prefixes/postfixes in file names, when the containing directory already contains the same</span></div>
<div class="line"><a id="l00151" name="l00151"></a><span class="lineno">  151</span><span class="comment"> *     info -- even if this would create two same-named files at different places in the directory tree.</span></div>
<div class="line"><a id="l00152" name="l00152"></a><span class="lineno">  152</span><span class="comment"> *     E.g., if you have D/node.hpp and D/asio/node.hpp, that&#39;s fine; don&#39;t name the latter D/asio/asio_node.hpp.</span></div>
<div class="line"><a id="l00153" name="l00153"></a><span class="lineno">  153</span><span class="comment"> *     - For that matter: follow the same guideline when naming types, functions, and so on.  I.e.,</span></div>
<div class="line"><a id="l00154" name="l00154"></a><span class="lineno">  154</span><span class="comment"> *       don&#39;t have asio::Asio_node; just asio::Node.  Yes, this may require disambiguation (by more fully qualifying</span></div>
<div class="line"><a id="l00155" name="l00155"></a><span class="lineno">  155</span><span class="comment"> *       identifiers at times) in code.  Nevertheless.  We must take a stand! */</span></div>
<div class="line"><a id="l00156" name="l00156"></a><span class="lineno">  156</span> </div>
<div class="line"><a id="l00157" name="l00157"></a><span class="lineno">  157</span><span class="comment">// -- STYLE GUIDE: File level --</span></div>
<div class="line"><a id="l00158" name="l00158"></a><span class="lineno">  158</span><span class="comment"></span> </div>
<div class="line"><a id="l00159" name="l00159"></a><span class="lineno">  159</span><span class="comment">/// @file</span></div>
<div class="line"><a id="l00160" name="l00160"></a><span class="lineno">  160</span><span class="comment"></span><span class="preprocessor">#pragma once</span></div>
<div class="line"><a id="l00161" name="l00161"></a><span class="lineno">  161</span> </div>
<div class="line"><a id="l00162" name="l00162"></a><span class="lineno">  162</span><span class="comment">/* - Every source file begins with @file, so that Doxygen will add it to its Files page in the generated docs.</span></div>
<div class="line"><a id="l00163" name="l00163"></a><span class="lineno">  163</span><span class="comment"> * - Every header then begins with that `pragma` to avoid redefinitions from multiple `#include`s.</span></div>
<div class="line"><a id="l00164" name="l00164"></a><span class="lineno">  164</span><span class="comment"> *</span></div>
<div class="line"><a id="l00165" name="l00165"></a><span class="lineno">  165</span><span class="comment"> * - File names are to be all-lower-case words, underscore-separated.</span></div>
<div class="line"><a id="l00166" name="l00166"></a><span class="lineno">  166</span><span class="comment"> *   - @todo Defining formal rules beyond that feels tedious... but technically we should.</span></div>
<div class="line"><a id="l00167" name="l00167"></a><span class="lineno">  167</span><span class="comment"> *     Until then follow the many existing examples.</span></div>
<div class="line"><a id="l00168" name="l00168"></a><span class="lineno">  168</span><span class="comment"> *   - Header file name ends with .hpp.</span></div>
<div class="line"><a id="l00169" name="l00169"></a><span class="lineno">  169</span><span class="comment"> *     - .h if file is intended as a C API (even if supports C++ use also).  This is rare.</span></div>
<div class="line"><a id="l00170" name="l00170"></a><span class="lineno">  170</span><span class="comment"> *   - Translation unit names ends with .cpp. */</span></div>
<div class="line"><a id="l00171" name="l00171"></a><span class="lineno">  171</span> </div>
<div class="line"><a id="l00172" name="l00172"></a><span class="lineno">  172</span><span class="comment">// This illustrates how to properly indent #directives.</span></div>
<div class="line"><a id="l00173" name="l00173"></a><span class="lineno">  173</span><span class="preprocessor">#ifdef FLOW_SOME_DEFINE</span></div>
<div class="line"><a id="l00174" name="l00174"></a><span class="lineno">  174</span><span class="preprocessor">#  if FLOW_SOME_OTHER_DEFINE</span></div>
<div class="line"><a id="l00175" name="l00175"></a><span class="lineno">  175</span><span class="preprocessor">#    include &quot;conditionally_included_file.hpp&quot;</span></div>
<div class="line"><a id="l00176" name="l00176"></a><span class="lineno">  176</span><span class="preprocessor">#  endif</span></div>
<div class="line"><a id="l00177" name="l00177"></a><span class="lineno">  177</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00178" name="l00178"></a><span class="lineno">  178</span><span class="comment">// The indentation of #directives is 100% orthogonal to indentation of actual code, as this shows:</span></div>
<div class="line"><a id="l00179" name="l00179"></a><span class="lineno">  179</span><span class="keywordtype">void</span> f(<span class="keywordtype">bool</span> flag)</div>
<div class="line"><a id="l00180" name="l00180"></a><span class="lineno">  180</span>{</div>
<div class="line"><a id="l00181" name="l00181"></a><span class="lineno">  181</span>  <span class="keywordflow">if</span> (flag)</div>
<div class="line"><a id="l00182" name="l00182"></a><span class="lineno">  182</span>  {</div>
<div class="line"><a id="l00183" name="l00183"></a><span class="lineno">  183</span><span class="preprocessor">#if FLOW_YET_ANOTHER_DEFINE</span></div>
<div class="line"><a id="l00184" name="l00184"></a><span class="lineno">  184</span>    do_something_conditionally_compiled();</div>
<div class="line"><a id="l00185" name="l00185"></a><span class="lineno">  185</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00186" name="l00186"></a><span class="lineno">  186</span>  }</div>
<div class="line"><a id="l00187" name="l00187"></a><span class="lineno">  187</span>}</div>
<div class="line"><a id="l00188" name="l00188"></a><span class="lineno">  188</span><span class="comment">/* Also, use the spirit of the rules for parenthesizing expressions to express priority even when unnecessary,</span></div>
<div class="line"><a id="l00189" name="l00189"></a><span class="lineno">  189</span><span class="comment"> * which are described elsewhere in this guide, not just for actual code expressions but also within #if directives.</span></div>
<div class="line"><a id="l00190" name="l00190"></a><span class="lineno">  190</span><span class="comment"> * There is however no need to surround the entire thing in (parentheses), as a regular `if ()` forces it, while</span></div>
<div class="line"><a id="l00191" name="l00191"></a><span class="lineno">  191</span><span class="comment"> * #if does not. */</span></div>
<div class="line"><a id="l00192" name="l00192"></a><span class="lineno">  192</span><span class="preprocessor">#if defined(FLOW_THING) &amp;&amp; ((!defined(FLOW_OTHER_THING)) || defined(FLOW_THIRD_THING))</span></div>
<div class="line"><a id="l00193" name="l00193"></a><span class="lineno">  193</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00194" name="l00194"></a><span class="lineno">  194</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00195" name="l00195"></a><span class="lineno">  195</span> </div>
<div class="line"><a id="l00196" name="l00196"></a><span class="lineno">  196</span><span class="comment">// -- STYLE GUIDE: Line width; indent; comments; doc header basics --</span></div>
<div class="line"><a id="l00197" name="l00197"></a><span class="lineno">  197</span> </div>
<div class="line"><a id="l00198" name="l00198"></a><span class="lineno">  198</span><span class="comment">/* - Lines are up to 120 columns, inclusive.  [Try &lt;110 to leave space for later edits.]</span></div>
<div class="line"><a id="l00199" name="l00199"></a><span class="lineno">  199</span><span class="comment"> * - One indent level = 2 spaces.  No tab characters.</span></div>
<div class="line"><a id="l00200" name="l00200"></a><span class="lineno">  200</span><span class="comment"> * - Comments should be composed of sentence-ish things.  Each sentence starts with a Capital and ends with a period</span></div>
<div class="line"><a id="l00201" name="l00201"></a><span class="lineno">  201</span><span class="comment"> *   or similar. [Optional: Use two spaces between sentence-ish things.  Many find this annoying; hence optional.]</span></div>
<div class="line"><a id="l00202" name="l00202"></a><span class="lineno">  202</span><span class="comment"> *</span></div>
<div class="line"><a id="l00203" name="l00203"></a><span class="lineno">  203</span><span class="comment"> * Multi-line comments use C-style comment markers like this. */</span></div>
<div class="line"><a id="l00204" name="l00204"></a><span class="lineno">  204</span> </div>
<div class="line"><a id="l00205" name="l00205"></a><span class="lineno">  205</span><span class="comment">// Single-line comments are C++-style like this.</span></div>
<div class="line"><a id="l00206" name="l00206"></a><span class="lineno">  206</span><span class="comment"></span> </div>
<div class="line"><a id="l00207" name="l00207"></a><span class="lineno">  207</span><span class="comment">/**</span></div>
<div class="line"><a id="l00208" name="l00208"></a><span class="lineno">  208</span><span class="comment"> * - Comments that start with 2 asterisks are *doc headers* and are understood by Doxygen to be documenting the entity</span></div>
<div class="line"><a id="l00209" name="l00209"></a><span class="lineno">  209</span><span class="comment"> *   immediately following.  Essentially *every* entity not inside the {braces} of a function -- files, macros,</span></div>
<div class="line"><a id="l00210" name="l00210"></a><span class="lineno">  210</span><span class="comment"> *   `class/struct/union/enum`s, functions, variables/constants, namespaces, aliases, ??? -- *must*</span></div>
<div class="line"><a id="l00211" name="l00211"></a><span class="lineno">  211</span><span class="comment"> *   have a doc header.  In this case we&#39;re documenting a `class`.  When documenting a function, always document</span></div>
<div class="line"><a id="l00212" name="l00212"></a><span class="lineno">  212</span><span class="comment"> *   its body-less prototype only.</span></div>
<div class="line"><a id="l00213" name="l00213"></a><span class="lineno">  213</span><span class="comment"> *   - We explain Doxygen details elsewhere in this file though.</span></div>
<div class="line"><a id="l00214" name="l00214"></a><span class="lineno">  214</span><span class="comment"> * - Do *not* place any doc headers inside {braces} of a function, such as for local variables.  Just comment, or not,</span></div>
<div class="line"><a id="l00215" name="l00215"></a><span class="lineno">  215</span><span class="comment"> *   as you see fit for clarity/etc.</span></div>
<div class="line"><a id="l00216" name="l00216"></a><span class="lineno">  216</span><span class="comment"> *</span></div>
<div class="line"><a id="l00217" name="l00217"></a><span class="lineno">  217</span><span class="comment"> * - Note doc headers have 1 extra leading and 1 trailing lines vs. non-Doxygen comments, as seen in this block.</span></div>
<div class="line"><a id="l00218" name="l00218"></a><span class="lineno">  218</span><span class="comment"> */</span></div>
<div class="line"><a id="l00219" name="l00219"></a><span class="lineno">  219</span><span class="keyword">class </span>Cool_class</div>
<div class="line"><a id="l00220" name="l00220"></a><span class="lineno">  220</span>{</div>
<div class="line"><a id="l00221" name="l00221"></a><span class="lineno">  221</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00222" name="l00222"></a><span class="lineno">  222</span><span class="comment"></span> </div>
<div class="line"><a id="l00223" name="l00223"></a><span class="lineno">  223</span><span class="comment">  /// Single-line *doc headers* are relatively rare but allowed and start with 3 slashes instead of 2.</span></div>
<div class="line"><a id="l00224" name="l00224"></a><span class="lineno">  224</span><span class="comment"></span>  <span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> S_COOL_CONSTANT_BEING_DOCUMENTED_WITH_A_ONE_LINE_DOC_HEADER;</div>
<div class="line"><a id="l00225" name="l00225"></a><span class="lineno">  225</span>  <span class="comment">//&lt; BAD: Don&#39;t use trailing doc headers like this.  [Rationale: Why add inconsistency?]</span></div>
<div class="line"><a id="l00226" name="l00226"></a><span class="lineno">  226</span> </div>
<div class="line"><a id="l00227" name="l00227"></a><span class="lineno">  227</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00228" name="l00228"></a><span class="lineno">  228</span>}; <span class="comment">// class Cool_class</span></div>
<div class="line"><a id="l00229" name="l00229"></a><span class="lineno">  229</span><span class="comment">/* ^-- Closing {braces} and possibly (parentheses) spanning screenfuls should usually feature a terminating comment</span></div>
<div class="line"><a id="l00230" name="l00230"></a><span class="lineno">  230</span><span class="comment"> * like that `// class Cool_class` one.  Typical conventions for how these end-comments look can be found across</span></div>
<div class="line"><a id="l00231" name="l00231"></a><span class="lineno">  231</span><span class="comment"> * Flow by example.  This style helps readability (but may make maintenance somewhat more annoying). */</span></div>
<div class="line"><a id="l00232" name="l00232"></a><span class="lineno">  232</span> </div>
<div class="line"><a id="l00233" name="l00233"></a><span class="lineno">  233</span><span class="comment">// -- STYLE GUIDE: Identifier formatting --</span></div>
<div class="line"><a id="l00234" name="l00234"></a><span class="lineno">  234</span> </div>
<div class="line"><a id="l00235" name="l00235"></a><span class="lineno">  235</span><span class="comment">/* Words-separated-by-underscores formatting is to be used by ALL identifers!</span></div>
<div class="line"><a id="l00236" name="l00236"></a><span class="lineno">  236</span><span class="comment"> *   - Do not use CamelCase or any variation.</span></div>
<div class="line"><a id="l00237" name="l00237"></a><span class="lineno">  237</span><span class="comment"> *   - Do not use wordsmooshing.  Is it two words?  Yes?  Then put an underscore _ between them.  Period!</span></div>
<div class="line"><a id="l00238" name="l00238"></a><span class="lineno">  238</span><span class="comment"> *</span></div>
<div class="line"><a id="l00239" name="l00239"></a><span class="lineno">  239</span><span class="comment"> * [Rationale: This decision to forego CamelCase in favor of underscores does not imply the latter is superior</span></div>
<div class="line"><a id="l00240" name="l00240"></a><span class="lineno">  240</span><span class="comment"> * in and of itself.  A case can be made for either approach, certainly with pros and cons for each.</span></div>
<div class="line"><a id="l00241" name="l00241"></a><span class="lineno">  241</span><span class="comment"> * The deciding factor for choosing underscores for Flow originally was that the STL *and* Boost ecosystems</span></div>
<div class="line"><a id="l00242" name="l00242"></a><span class="lineno">  242</span><span class="comment"> * so heavily affected the project that it seemed strange to intentionally allow the visual clashing between</span></div>
<div class="line"><a id="l00243" name="l00243"></a><span class="lineno">  243</span><span class="comment"> * STL/Boost identifiers and Flow ones when seen side-by-side in real code (in and out of Flow itself).</span></div>
<div class="line"><a id="l00244" name="l00244"></a><span class="lineno">  244</span><span class="comment"> *</span></div>
<div class="line"><a id="l00245" name="l00245"></a><span class="lineno">  245</span><span class="comment"> * A certain large code project used CamelCase and thus provided a counterpoint.  However, even that unnamed</span></div>
<div class="line"><a id="l00246" name="l00246"></a><span class="lineno">  246</span><span class="comment"> * project had tons of core code that used under_score_style after all; and there&#39;s plenty of wordsmooshing too.</span></div>
<div class="line"><a id="l00247" name="l00247"></a><span class="lineno">  247</span><span class="comment"> * So if it&#39;s not even consistent in the first place... meh.  We do what&#39;s best.] */</span></div>
<div class="line"><a id="l00248" name="l00248"></a><span class="lineno">  248</span> </div>
<div class="line"><a id="l00249" name="l00249"></a><span class="lineno">  249</span><span class="comment">/* - Every identifier consists of a root; a possible prefix (s_, m_, S_); and a possible suffix (_t).</span></div>
<div class="line"><a id="l00250" name="l00250"></a><span class="lineno">  250</span><span class="comment"> * - The root = always 1+ words, separated by underscores if 2+.</span></div>
<div class="line"><a id="l00251" name="l00251"></a><span class="lineno">  251</span><span class="comment"> * - Each words consists of ASCII letters and numbers only.  The first word in root must start with letter.</span></div>
<div class="line"><a id="l00252" name="l00252"></a><span class="lineno">  252</span><span class="comment"> *</span></div>
<div class="line"><a id="l00253" name="l00253"></a><span class="lineno">  253</span><span class="comment"> * - Most roots are all-lower-case: */</span></div>
<div class="line"><a id="l00254" name="l00254"></a><span class="lineno">  254</span>word;</div>
<div class="line"><a id="l00255" name="l00255"></a><span class="lineno">  255</span>two_words;</div>
<div class="line"><a id="l00256" name="l00256"></a><span class="lineno">  256</span>three_or_4_words;</div>
<div class="line"><a id="l00257" name="l00257"></a><span class="lineno">  257</span>identifier_version1_or_v2;</div>
<div class="line"><a id="l00258" name="l00258"></a><span class="lineno">  258</span>acronyms_are_just_words_eg_url;</div>
<div class="line"><a id="l00259" name="l00259"></a><span class="lineno">  259</span>wordsmooshing_abbrevs_like_uint_are_ok_if_very_well_known;</div>
<div class="line"><a id="l00260" name="l00260"></a><span class="lineno">  260</span> </div>
<div class="line"><a id="l00261" name="l00261"></a><span class="lineno">  261</span><span class="comment">// However, compound types must start with a single Capital letter but otherwise all-lower-case:</span></div>
<div class="line"><a id="l00262" name="l00262"></a><span class="lineno">  262</span><span class="keyword">class </span>First_letter_of_a_class_is_capital_while_rest_always_lower_case;</div>
<div class="line"><a id="l00263" name="l00263"></a><span class="lineno">  263</span><span class="keyword">struct </span>Same_format_for_struct;</div>
<div class="line"><a id="l00264" name="l00264"></a><span class="lineno">  264</span><span class="keyword">union </span>Same_format_for_union;</div>
<div class="line"><a id="l00265" name="l00265"></a><span class="lineno">  265</span><span class="keyword">enum</span> Same_format_for_old_enum; <span class="comment">// Non-`class` `enum` is considered a compound type for our purposes.</span></div>
<div class="line"><a id="l00266" name="l00266"></a><span class="lineno">  266</span><span class="keyword">enum class</span> Same_format_for_new_enum; <span class="comment">// In any case always use `enum class` if possible, not plain `enum`.</span></div>
<div class="line"><a id="l00267" name="l00267"></a><span class="lineno">  267</span><span class="keyword">using </span>Typedefs_thereof_as_well = <span class="comment">/* [anything resolving to a compound type] */</span>;</div>
<div class="line"><a id="l00268" name="l00268"></a><span class="lineno">  268</span><span class="comment">// However, if an alias is to a non-compound type -- typically integers, etc. -- do *not* capitalize but add _t suffix:</span></div>
<div class="line"><a id="l00269" name="l00269"></a><span class="lineno">  269</span><span class="keyword">using </span><a class="code hl_typedef" href="namespaceflow.html#ae02da22c4a101eaab447511c905e4f32">uint8_t</a> = <span class="keywordtype">unsigned</span> char;</div>
<div class="line"><a id="l00270" name="l00270"></a><span class="lineno">  270</span><span class="keyword">using </span>ptr_diff_t = <span class="keywordtype">signed</span> <span class="keywordtype">long</span> long;</div>
<div class="line"><a id="l00271" name="l00271"></a><span class="lineno">  271</span><span class="comment">/* BAD: Do not use `typedef`.</span></div>
<div class="line"><a id="l00272" name="l00272"></a><span class="lineno">  272</span><span class="comment"> * Use `using` (for consistency + its extra features, esp. template parameterization, shown just below).</span></div>
<div class="line"><a id="l00273" name="l00273"></a><span class="lineno">  273</span><span class="comment"> *   typedef signed long long ptr_diff_t;</span></div>
<div class="line"><a id="l00274" name="l00274"></a><span class="lineno">  274</span><span class="comment"> *   typedef [anything resolving to a compound type] Typedefs_thereof_as_well; */</span></div>
<div class="line"><a id="l00275" name="l00275"></a><span class="lineno">  275</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Param_type&gt;</div>
<div class="line"><a id="l00276" name="l00276"></a><span class="lineno">  276</span><span class="keyword">using </span>Parameterized_alias</div>
<div class="line"><a id="l00277" name="l00277"></a><span class="lineno">  277</span>  = <span class="comment">/* [anything resolving to a compound type, with Param_type as part of this alias definition] */</span>;</div>
<div class="line"><a id="l00278" name="l00278"></a><span class="lineno">  278</span><span class="comment">// Now one can use Parameterized_alias&lt;X&gt; for any X.</span></div>
<div class="line"><a id="l00279" name="l00279"></a><span class="lineno">  279</span> </div>
<div class="line"><a id="l00280" name="l00280"></a><span class="lineno">  280</span><span class="comment">// Most roots are lower-case (first letter aside possibly), but a couple of things must use ALL-CAPS:</span></div>
<div class="line"><a id="l00281" name="l00281"></a><span class="lineno">  281</span><span class="comment">// `#define`d symbols:</span></div>
<div class="line"><a id="l00282" name="l00282"></a><span class="lineno">  282</span><span class="preprocessor">#define MACROS_ARE_IN_CAPS </span><span class="comment">/* [...] */</span><span class="preprocessor"></span></div>
<div class="line"><a id="l00283" name="l00283"></a><span class="lineno">  283</span><span class="preprocessor">#define FUNC_MACROS_ARE_2(</span><span class="comment">/* [...] */</span><span class="preprocessor">) </span><span class="comment">/* [...] */</span><span class="preprocessor"></span></div>
<div class="line"><a id="l00284" name="l00284"></a><span class="lineno">  284</span><span class="comment">// Constants in func body:</span></div>
<div class="line"><a id="l00285" name="l00285"></a><span class="lineno">  285</span>{</div>
<div class="line"><a id="l00286" name="l00286"></a><span class="lineno">  286</span>  <span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">int</span> STATIC_CONSTANT = <span class="comment">/* [...] */</span>;</div>
<div class="line"><a id="l00287" name="l00287"></a><span class="lineno">  287</span>  <span class="keyword">const</span> <span class="keywordtype">float</span> LOCAL_NON_STATIC_CONSTANT = 2.3; <span class="comment">// Value known at compile time =&gt; consider it a constant =&gt; all caps.</span></div>
<div class="line"><a id="l00288" name="l00288"></a><span class="lineno">  288</span>  <span class="comment">// Value not straightforwardly known at compile time =&gt; not a &quot;constant&quot; in this context =&gt; all-lower-case after all.</span></div>
<div class="line"><a id="l00289" name="l00289"></a><span class="lineno">  289</span>  <span class="keyword">const</span> <span class="keyword">auto</span>&amp; blah_ref = *blah_ptr_arg;</div>
<div class="line"><a id="l00290" name="l00290"></a><span class="lineno">  290</span>}</div>
<div class="line"><a id="l00291" name="l00291"></a><span class="lineno">  291</span><span class="keyword">enum class</span> <span class="comment">/* [...] */</span></div>
<div class="line"><a id="l00292" name="l00292"></a><span class="lineno">  292</span><span class="comment">// or: enum /* [...] */</span></div>
<div class="line"><a id="l00293" name="l00293"></a><span class="lineno">  293</span>{</div>
<div class="line"><a id="l00294" name="l00294"></a><span class="lineno">  294</span>  S_ENUM_VALUES_ARE_CONSTANTS_TOO, <span class="comment">// S_ prefix explained below.</span></div>
<div class="line"><a id="l00295" name="l00295"></a><span class="lineno">  295</span>  S_ENUM_VALUES_ARE_CONSTANTS_3 = 3</div>
<div class="line"><a id="l00296" name="l00296"></a><span class="lineno">  296</span>};</div>
<div class="line"><a id="l00297" name="l00297"></a><span class="lineno">  297</span> </div>
<div class="line"><a id="l00298" name="l00298"></a><span class="lineno">  298</span><span class="comment">// So, those are the roots.  What about prefixes and postfixes?  Simple:</span></div>
<div class="line"><a id="l00299" name="l00299"></a><span class="lineno">  299</span> </div>
<div class="line"><a id="l00300" name="l00300"></a><span class="lineno">  300</span><span class="comment">// Only one postfix exists: _t, used for aliases of non-compound types.  See 2 examples above.</span></div>
<div class="line"><a id="l00301" name="l00301"></a><span class="lineno">  301</span><span class="comment">// Three prefixes exist: s_, m_, S_:</span></div>
<div class="line"><a id="l00302" name="l00302"></a><span class="lineno">  302</span> </div>
<div class="line"><a id="l00303" name="l00303"></a><span class="lineno">  303</span><span class="comment">/* Anything `static` must be prefixed with s_ or S_ depending on capitalization chosen above for the root.</span></div>
<div class="line"><a id="l00304" name="l00304"></a><span class="lineno">  304</span><span class="comment"> * That includes file-level, compound member, even local `static`s; plus `enum` members (technically not `static`). */</span></div>
<div class="line"><a id="l00305" name="l00305"></a><span class="lineno">  305</span><span class="keyword">static</span> Cool_class s_singleton_instance; <span class="comment">// Not a constant.</span></div>
<div class="line"><a id="l00306" name="l00306"></a><span class="lineno">  306</span><span class="keyword">static</span> <span class="keyword">const</span> std::string S_STRING_VAR; <span class="comment">// Constant.</span></div>
<div class="line"><a id="l00307" name="l00307"></a><span class="lineno">  307</span><span class="comment">// `enum` values are constants.  They must be prefixed with S_ (see `S_ENUM_VALUES_ARE_CONSTANTS_3` above).</span></div>
<div class="line"><a id="l00308" name="l00308"></a><span class="lineno">  308</span> </div>
<div class="line"><a id="l00309" name="l00309"></a><span class="lineno">  309</span><span class="comment">/* Any non-static member variable of a compound type, a/k/a *data member*, must be prefixed with m_.</span></div>
<div class="line"><a id="l00310" name="l00310"></a><span class="lineno">  310</span><span class="comment"> * Since a member constant is by definition `static`, there is no M_ prefix but an S_ prefix.</span></div>
<div class="line"><a id="l00311" name="l00311"></a><span class="lineno">  311</span><span class="comment"> * A static member variable has s_ prefix.</span></div>
<div class="line"><a id="l00312" name="l00312"></a><span class="lineno">  312</span><span class="comment"> * A local variable, or a local constant, carries no prefix.</span></div>
<div class="line"><a id="l00313" name="l00313"></a><span class="lineno">  313</span><span class="comment"> * A global non-member non-static constant (probably rare) carries no prefix.</span></div>
<div class="line"><a id="l00314" name="l00314"></a><span class="lineno">  314</span><span class="comment"> * Same with global non-member non-static variable (even rarer). */</span></div>
<div class="line"><a id="l00315" name="l00315"></a><span class="lineno">  315</span><span class="keyword">extern</span> <span class="keywordtype">int</span> no_prefix_because_not_a_member_nor_static; <span class="comment">// .hpp</span></div>
<div class="line"><a id="l00316" name="l00316"></a><span class="lineno">  316</span><span class="keyword">extern</span> <span class="keywordtype">int</span> NO_PREFIX_BECAUSE_NOT_A_MEMBER_NOR_STATIC; <span class="comment">// .hpp</span></div>
<div class="line"><a id="l00317" name="l00317"></a><span class="lineno">  317</span><span class="keywordtype">int</span> no_prefix_because_not_a_member_nor_static; <span class="comment">// .cpp</span></div>
<div class="line"><a id="l00318" name="l00318"></a><span class="lineno">  318</span><span class="keywordtype">int</span> NO_PREFIX_BECAUSE_NOT_A_MEMBER_NOR_STATIC; <span class="comment">// .cpp</span></div>
<div class="line"><a id="l00319" name="l00319"></a><span class="lineno">  319</span><span class="keyword">class </span>Some_class</div>
<div class="line"><a id="l00320" name="l00320"></a><span class="lineno">  320</span>{</div>
<div class="line"><a id="l00321" name="l00321"></a><span class="lineno">  321</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00322" name="l00322"></a><span class="lineno">  322</span>  <span class="keyword">const</span> Some_class&amp; m_data_member_is_a_ref;</div>
<div class="line"><a id="l00323" name="l00323"></a><span class="lineno">  323</span>  Some_enum m_enum_data_member;</div>
<div class="line"><a id="l00324" name="l00324"></a><span class="lineno">  324</span>  <span class="keyword">static</span> <span class="keyword">const</span> Some_type S_CONSTANT_MEMBER;</div>
<div class="line"><a id="l00325" name="l00325"></a><span class="lineno">  325</span>  <span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keywordtype">int</span> S_CONSTANT_MEMBER = 32;</div>
<div class="line"><a id="l00326" name="l00326"></a><span class="lineno">  326</span>  <span class="keyword">static</span> Some_type s_variable_member;</div>
<div class="line"><a id="l00327" name="l00327"></a><span class="lineno">  327</span>  <span class="keywordtype">void</span> some_func()</div>
<div class="line"><a id="l00328" name="l00328"></a><span class="lineno">  328</span>  {</div>
<div class="line"><a id="l00329" name="l00329"></a><span class="lineno">  329</span>    <span class="keywordtype">int</span> no_prefix_because_not_a_member;</div>
<div class="line"><a id="l00330" name="l00330"></a><span class="lineno">  330</span>    <span class="keyword">const</span> <span class="keywordtype">int</span> NO_PREFIX_BECAUSE_NOT_A_MEMBER = 2;</div>
<div class="line"><a id="l00331" name="l00331"></a><span class="lineno">  331</span>    <span class="keyword">constexpr</span> <span class="keywordtype">int</span> NO_PREFIX_BECAUSE_NOT_A_MEMBER = 3;</div>
<div class="line"><a id="l00332" name="l00332"></a><span class="lineno">  332</span>    <span class="comment">// [...]</span></div>
<div class="line"><a id="l00333" name="l00333"></a><span class="lineno">  333</span>  }</div>
<div class="line"><a id="l00334" name="l00334"></a><span class="lineno">  334</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00335" name="l00335"></a><span class="lineno">  335</span>}</div>
<div class="line"><a id="l00336" name="l00336"></a><span class="lineno">  336</span> </div>
<div class="line"><a id="l00337" name="l00337"></a><span class="lineno">  337</span><span class="comment">// -- STYLE GUIDE: Order of declarations --</span></div>
<div class="line"><a id="l00338" name="l00338"></a><span class="lineno">  338</span> </div>
<div class="line"><a id="l00339" name="l00339"></a><span class="lineno">  339</span><span class="comment">/* Flow style cares about ordering things consistently and readably, more than usual in my opinion.</span></div>
<div class="line"><a id="l00340" name="l00340"></a><span class="lineno">  340</span><span class="comment"> *</span></div>
<div class="line"><a id="l00341" name="l00341"></a><span class="lineno">  341</span><span class="comment"> * - Basic principle: Whenever an API and implementation for anything is written -- including APIs used only</span></div>
<div class="line"><a id="l00342" name="l00342"></a><span class="lineno">  342</span><span class="comment"> *   internally -- the API (black box) must come first; implementation (white box) second.  In other words,</span></div>
<div class="line"><a id="l00343" name="l00343"></a><span class="lineno">  343</span><span class="comment"> *   when *declaring*, start with public, end with private (protected in middle if applicable).</span></div>
<div class="line"><a id="l00344" name="l00344"></a><span class="lineno">  344</span><span class="comment"> *   [Rationale: User of entity X cares how to use X, not what&#39;s inside X -- ideally.  So the public parts come first.</span></div>
<div class="line"><a id="l00345" name="l00345"></a><span class="lineno">  345</span><span class="comment"> *   Plus it adds consistency.]</span></div>
<div class="line"><a id="l00346" name="l00346"></a><span class="lineno">  346</span><span class="comment"> *   - The function *bodies* need not follow any such order, so just do what feels right.</span></div>
<div class="line"><a id="l00347" name="l00347"></a><span class="lineno">  347</span><span class="comment"> * - Basic principle: Whenever in some section of an API or implementation (notably a `public:` or `private:` section</span></div>
<div class="line"><a id="l00348" name="l00348"></a><span class="lineno">  348</span><span class="comment"> *   of a `class` or `struct`), follow the same consistent order of grouped items:</span></div>
<div class="line"><a id="l00349" name="l00349"></a><span class="lineno">  349</span><span class="comment"> *   - The order is: types, constructors/destructor, functions (including `operator`s), constants (i.e., all-caps</span></div>
<div class="line"><a id="l00350" name="l00350"></a><span class="lineno">  350</span><span class="comment"> *     things), data members.  [Rationale: Roughly speaking it follows a black box-&gt;white box ordering.]</span></div>
<div class="line"><a id="l00351" name="l00351"></a><span class="lineno">  351</span><span class="comment"> *     (`static` or otherwise).</span></div>
<div class="line"><a id="l00352" name="l00352"></a><span class="lineno">  352</span><span class="comment"> *     - However, data-store `struct`s should place constructors/destructor and functions at the bottom instead.</span></div>
<div class="line"><a id="l00353" name="l00353"></a><span class="lineno">  353</span><span class="comment"> * - Basic principle: There is a standard order of items in each file but especially for headers .hpp.</span></div>
<div class="line"><a id="l00354" name="l00354"></a><span class="lineno">  354</span><span class="comment"> *   Follow the order in the snippets below.</span></div>
<div class="line"><a id="l00355" name="l00355"></a><span class="lineno">  355</span><span class="comment"> * - Basic principle: Human nature: The ordering guidelines are easy to forget to follow.  To encourage it, label</span></div>
<div class="line"><a id="l00356" name="l00356"></a><span class="lineno">  356</span><span class="comment"> *   each grouping with a standard comment (e.g., &quot;// Constructors/destructor.&quot;, &quot;// Data.&quot;, etc.).  Snippets below.</span></div>
<div class="line"><a id="l00357" name="l00357"></a><span class="lineno">  357</span><span class="comment"> *   - Do NOT have &quot;empty&quot; such headers (e.g., if there are no data members then no &quot;// Data.&quot; comment either).</span></div>
<div class="line"><a id="l00358" name="l00358"></a><span class="lineno">  358</span><span class="comment"> * - Basic principle: Exceptions to these guidelines will happen and aren&#39;t the end of the world at all. */</span></div>
<div class="line"><a id="l00359" name="l00359"></a><span class="lineno">  359</span> </div>
<div class="line"><a id="l00360" name="l00360"></a><span class="lineno">  360</span><span class="comment">// order.hpp follows: Illustrates above principles/shows proper ordering by example, in a header file:</span></div>
<div class="line"><a id="l00361" name="l00361"></a><span class="lineno">  361</span><span class="comment"></span> </div>
<div class="line"><a id="l00362" name="l00362"></a><span class="lineno">  362</span><span class="comment">/// @file</span></div>
<div class="line"><a id="l00363" name="l00363"></a><span class="lineno">  363</span><span class="comment"></span><span class="preprocessor">#pragma once</span></div>
<div class="line"><a id="l00364" name="l00364"></a><span class="lineno">  364</span> </div>
<div class="line"><a id="l00365" name="l00365"></a><span class="lineno">  365</span><span class="preprocessor">#include &quot;own_headers_included_first.hpp&quot;</span></div>
<div class="line"><a id="l00366" name="l00366"></a><span class="lineno">  366</span><span class="preprocessor">#include &lt;boost/higher_level_angly_headers_go_next.hpp&gt;</span></div>
<div class="line"><a id="l00367" name="l00367"></a><span class="lineno">  367</span><span class="preprocessor">#include &lt;vector&gt;</span> <span class="comment">// STL- and lower-level includes typically bring up the rear.</span></div>
<div class="line"><a id="l00368" name="l00368"></a><span class="lineno">  368</span> </div>
<div class="line"><a id="l00369" name="l00369"></a><span class="lineno">  369</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00370" name="l00370"></a><span class="lineno">  370</span><span class="comment">/* As prescribed just above, precede groupings of like things with these standard, single-line comments like:</span></div>
<div class="line"><a id="l00371" name="l00371"></a><span class="lineno">  371</span><span class="comment"> * Again, this helps maintain discipline and set a good example.</span></div>
<div class="line"><a id="l00372" name="l00372"></a><span class="lineno">  372</span><span class="comment"> * Reiterate: DO omit such a heading when that &quot;section&quot; is empty. */</span></div>
<div class="line"><a id="l00373" name="l00373"></a><span class="lineno">  373</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00374" name="l00374"></a><span class="lineno">  374</span> </div>
<div class="line"><a id="l00375" name="l00375"></a><span class="lineno">  375</span><span class="comment">// Types.</span></div>
<div class="line"><a id="l00376" name="l00376"></a><span class="lineno">  376</span><span class="comment"></span> </div>
<div class="line"><a id="l00377" name="l00377"></a><span class="lineno">  377</span><span class="comment">/// Short-hand for boost::any.  Any ordering is fine within the //Types grouping.</span></div>
<div class="line"><a id="l00378" name="l00378"></a><span class="lineno">  378</span><span class="comment"></span><span class="keyword">using </span>Cool_type = boost::any;</div>
<div class="line"><a id="l00379" name="l00379"></a><span class="lineno">  379</span><span class="comment"></span> </div>
<div class="line"><a id="l00380" name="l00380"></a><span class="lineno">  380</span><span class="comment">/**</span></div>
<div class="line"><a id="l00381" name="l00381"></a><span class="lineno">  381</span><span class="comment"> * A class that accomplishes so-and-so.</span></div>
<div class="line"><a id="l00382" name="l00382"></a><span class="lineno">  382</span><span class="comment"> * Similarly with structs, unions, whatever.</span></div>
<div class="line"><a id="l00383" name="l00383"></a><span class="lineno">  383</span><span class="comment"> */</span></div>
<div class="line"><a id="l00384" name="l00384"></a><span class="lineno">  384</span><span class="keyword">class </span>Cool_class</div>
<div class="line"><a id="l00385" name="l00385"></a><span class="lineno">  385</span>{</div>
<div class="line"><a id="l00386" name="l00386"></a><span class="lineno">  386</span><span class="keyword">public</span>:</div>
<div class="line"><a id="l00387" name="l00387"></a><span class="lineno">  387</span>  <span class="comment">// [...Follow order as shown in private: below....]</span></div>
<div class="line"><a id="l00388" name="l00388"></a><span class="lineno">  388</span><span class="keyword">protected</span>:</div>
<div class="line"><a id="l00389" name="l00389"></a><span class="lineno">  389</span>  <span class="comment">// [...Follow order as shown in private: below....]</span></div>
<div class="line"><a id="l00390" name="l00390"></a><span class="lineno">  390</span><span class="keyword">private</span>:</div>
<div class="line"><a id="l00391" name="l00391"></a><span class="lineno">  391</span>  <span class="comment">// Friends.</span></div>
<div class="line"><a id="l00392" name="l00392"></a><span class="lineno">  392</span><span class="comment"></span> </div>
<div class="line"><a id="l00393" name="l00393"></a><span class="lineno">  393</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00394" name="l00394"></a><span class="lineno">  394</span><span class="comment">   * Server_socket must be able to forward `accept()`, etc. to Cool_class.</span></div>
<div class="line"><a id="l00395" name="l00395"></a><span class="lineno">  395</span><span class="comment">   * This documents a `friend` relationship.</span></div>
<div class="line"><a id="l00396" name="l00396"></a><span class="lineno">  396</span><span class="comment">   *</span></div>
<div class="line"><a id="l00397" name="l00397"></a><span class="lineno">  397</span><span class="comment">   * Can also have function `friend`s here, though they don&#39;t require official doc headers.</span></div>
<div class="line"><a id="l00398" name="l00398"></a><span class="lineno">  398</span><span class="comment">   */</span></div>
<div class="line"><a id="l00399" name="l00399"></a><span class="lineno">  399</span>  <span class="keyword">friend</span> <span class="keyword">class </span>Server_socket;</div>
<div class="line"><a id="l00400" name="l00400"></a><span class="lineno">  400</span> </div>
<div class="line"><a id="l00401" name="l00401"></a><span class="lineno">  401</span>  <span class="comment">// Types.</span></div>
<div class="line"><a id="l00402" name="l00402"></a><span class="lineno">  402</span><span class="comment"></span> </div>
<div class="line"><a id="l00403" name="l00403"></a><span class="lineno">  403</span><span class="comment">  /// Short-hand for ref-counted pointer to this class.</span></div>
<div class="line"><a id="l00404" name="l00404"></a><span class="lineno">  404</span><span class="comment"></span>  <span class="keyword">using </span>Ptr = boost::shared_ptr&lt;Cool_class&gt;;</div>
<div class="line"><a id="l00405" name="l00405"></a><span class="lineno">  405</span><span class="comment"></span> </div>
<div class="line"><a id="l00406" name="l00406"></a><span class="lineno">  406</span><span class="comment">  /// An inner class (struct, union, enum, enum class, etc.).  Declare its body outside whenever possible!</span></div>
<div class="line"><a id="l00407" name="l00407"></a><span class="lineno">  407</span><span class="comment"></span>  <span class="keyword">struct </span>Inner_class_of_cool;</div>
<div class="line"><a id="l00408" name="l00408"></a><span class="lineno">  408</span> </div>
<div class="line"><a id="l00409" name="l00409"></a><span class="lineno">  409</span>  <span class="comment">// Constructors/destructor.</span></div>
<div class="line"><a id="l00410" name="l00410"></a><span class="lineno">  410</span><span class="comment"></span> </div>
<div class="line"><a id="l00411" name="l00411"></a><span class="lineno">  411</span><span class="comment">  /// Constructs the object.</span></div>
<div class="line"><a id="l00412" name="l00412"></a><span class="lineno">  412</span><span class="comment"></span>  Cool_class();</div>
<div class="line"><a id="l00413" name="l00413"></a><span class="lineno">  413</span><span class="comment"></span> </div>
<div class="line"><a id="l00414" name="l00414"></a><span class="lineno">  414</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00415" name="l00415"></a><span class="lineno">  415</span><span class="comment">   * Copies object into newly created `*this`.</span></div>
<div class="line"><a id="l00416" name="l00416"></a><span class="lineno">  416</span><span class="comment">   * @param src</span></div>
<div class="line"><a id="l00417" name="l00417"></a><span class="lineno">  417</span><span class="comment">   *        Source.</span></div>
<div class="line"><a id="l00418" name="l00418"></a><span class="lineno">  418</span><span class="comment">   */</span></div>
<div class="line"><a id="l00419" name="l00419"></a><span class="lineno">  419</span>  Cool_class(<span class="keyword">const</span> Cool_class&amp; src);</div>
<div class="line"><a id="l00420" name="l00420"></a><span class="lineno">  420</span><span class="comment"></span> </div>
<div class="line"><a id="l00421" name="l00421"></a><span class="lineno">  421</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00422" name="l00422"></a><span class="lineno">  422</span><span class="comment">   * Explicitly deleted (possibly would-have-been-auto-generated) ctors and operators are so declared.</span></div>
<div class="line"><a id="l00423" name="l00423"></a><span class="lineno">  423</span><span class="comment">   * @param src</span></div>
<div class="line"><a id="l00424" name="l00424"></a><span class="lineno">  424</span><span class="comment">   *        Source.</span></div>
<div class="line"><a id="l00425" name="l00425"></a><span class="lineno">  425</span><span class="comment">   */</span></div>
<div class="line"><a id="l00426" name="l00426"></a><span class="lineno">  426</span>  Cool_class(Cool_class&amp;&amp;) = <span class="keyword">delete</span>;</div>
<div class="line"><a id="l00427" name="l00427"></a><span class="lineno">  427</span><span class="comment"></span> </div>
<div class="line"><a id="l00428" name="l00428"></a><span class="lineno">  428</span><span class="comment">  /// Boring destructor.</span></div>
<div class="line"><a id="l00429" name="l00429"></a><span class="lineno">  429</span><span class="comment"></span>  <span class="keyword">virtual</span> ~Cool_class();</div>
<div class="line"><a id="l00430" name="l00430"></a><span class="lineno">  430</span> </div>
<div class="line"><a id="l00431" name="l00431"></a><span class="lineno">  431</span>  <span class="comment">// Methods.</span></div>
<div class="line"><a id="l00432" name="l00432"></a><span class="lineno">  432</span><span class="comment"></span> </div>
<div class="line"><a id="l00433" name="l00433"></a><span class="lineno">  433</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00434" name="l00434"></a><span class="lineno">  434</span><span class="comment">   * Copies object `src` onto `*this`.</span></div>
<div class="line"><a id="l00435" name="l00435"></a><span class="lineno">  435</span><span class="comment">   * Operators are considered just methods in this context but tend to come first due to `operator=()` being</span></div>
<div class="line"><a id="l00436" name="l00436"></a><span class="lineno">  436</span><span class="comment">   * conveniently placed near copy constructors and similar.</span></div>
<div class="line"><a id="l00437" name="l00437"></a><span class="lineno">  437</span><span class="comment">   *</span></div>
<div class="line"><a id="l00438" name="l00438"></a><span class="lineno">  438</span><span class="comment">   * @param src</span></div>
<div class="line"><a id="l00439" name="l00439"></a><span class="lineno">  439</span><span class="comment">   *        Source.</span></div>
<div class="line"><a id="l00440" name="l00440"></a><span class="lineno">  440</span><span class="comment">   */</span></div>
<div class="line"><a id="l00441" name="l00441"></a><span class="lineno">  441</span>  Cool_class&amp; operator=(<span class="keyword">const</span> Cool_class&amp; src)</div>
<div class="line"><a id="l00442" name="l00442"></a><span class="lineno">  442</span> </div>
<div class="line"><a id="l00443" name="l00443"></a><span class="lineno">  443</span>  <span class="comment">/**</span></div>
<div class="line"><a id="l00444" name="l00444"></a><span class="lineno">  444</span><span class="comment">   * A regular method.</span></div>
<div class="line"><a id="l00445" name="l00445"></a><span class="lineno">  445</span><span class="comment">   *</span></div>
<div class="line"><a id="l00446" name="l00446"></a><span class="lineno">  446</span><span class="comment">   * Prototype only!  Template and inline function bodies MUST be outside class body (see below).</span></div>
<div class="line"><a id="l00447" name="l00447"></a><span class="lineno">  447</span><span class="comment">   */</span></div>
<div class="line"><a id="l00448" name="l00448"></a><span class="lineno">  448</span>  <span class="keywordtype">void</span> cool_method();</div>
<div class="line"><a id="l00449" name="l00449"></a><span class="lineno">  449</span>  <span class="comment">/* ^-- BTW, no m_ (or other prefix) to indicate a method is private.</span></div>
<div class="line"><a id="l00450" name="l00450"></a><span class="lineno">  450</span><span class="comment">   * [Rationale: Some like such a convention, but in my experience it&#39;s too easy to forget and a huge pain to maintain,</span></div>
<div class="line"><a id="l00451" name="l00451"></a><span class="lineno">  451</span><span class="comment">   * as public things often become private and vice versa... no one wants to do that renaming.  Goes bad even with good</span></div>
<div class="line"><a id="l00452" name="l00452"></a><span class="lineno">  452</span><span class="comment">   * intentions in my experience.] */</span></div>
<div class="line"><a id="l00453" name="l00453"></a><span class="lineno">  453</span><span class="comment"></span> </div>
<div class="line"><a id="l00454" name="l00454"></a><span class="lineno">  454</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00455" name="l00455"></a><span class="lineno">  455</span><span class="comment">   * A method template.</span></div>
<div class="line"><a id="l00456" name="l00456"></a><span class="lineno">  456</span><span class="comment">   * @tparam Some_type</span></div>
<div class="line"><a id="l00457" name="l00457"></a><span class="lineno">  457</span><span class="comment">   *         Document any template parameters.</span></div>
<div class="line"><a id="l00458" name="l00458"></a><span class="lineno">  458</span><span class="comment">   */</span></div>
<div class="line"><a id="l00459" name="l00459"></a><span class="lineno">  459</span>  <span class="keyword">template</span>&lt;<span class="keyword">typename</span> Some_type&gt;</div>
<div class="line"><a id="l00460" name="l00460"></a><span class="lineno">  460</span>  Some_type cool_template_method();</div>
<div class="line"><a id="l00461" name="l00461"></a><span class="lineno">  461</span> </div>
<div class="line"><a id="l00462" name="l00462"></a><span class="lineno">  462</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00463" name="l00463"></a><span class="lineno">  463</span><span class="comment">/* If this is a pure data-store `struct`, ideally move the below (constants/data) above</span></div>
<div class="line"><a id="l00464" name="l00464"></a><span class="lineno">  464</span><span class="comment"> * constructors/destructor/functions, as in that case the data are the &quot;star.&quot; */</span></div>
<div class="line"><a id="l00465" name="l00465"></a><span class="lineno">  465</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00466" name="l00466"></a><span class="lineno">  466</span> </div>
<div class="line"><a id="l00467" name="l00467"></a><span class="lineno">  467</span>  <span class="comment">// Constants.</span></div>
<div class="line"><a id="l00468" name="l00468"></a><span class="lineno">  468</span><span class="comment"></span> </div>
<div class="line"><a id="l00469" name="l00469"></a><span class="lineno">  469</span><span class="comment">  /**</span></div>
<div class="line"><a id="l00470" name="l00470"></a><span class="lineno">  470</span><span class="comment">   * Constants formally come before other data; and are always static.</span></div>
<div class="line"><a id="l00471" name="l00471"></a><span class="lineno">  471</span><span class="comment">   * Reminder: If it doesn&#39;t have a value straightforwardly known at compile time, it&#39;s not a constant and not</span></div>
<div class="line"><a id="l00472" name="l00472"></a><span class="lineno">  472</span><span class="comment">   * upper-case.</span></div>
<div class="line"><a id="l00473" name="l00473"></a><span class="lineno">  473</span><span class="comment">   */</span></div>
<div class="line"><a id="l00474" name="l00474"></a><span class="lineno">  474</span>  <span class="keyword">static</span> <span class="keyword">const</span> <span class="keywordtype">float</span> S_PI;</div>
<div class="line"><a id="l00475" name="l00475"></a><span class="lineno">  475</span> </div>
<div class="line"><a id="l00476" name="l00476"></a><span class="lineno">  476</span>  <span class="comment">// Data.</span></div>
<div class="line"><a id="l00477" name="l00477"></a><span class="lineno">  477</span><span class="comment"></span> </div>
<div class="line"><a id="l00478" name="l00478"></a><span class="lineno">  478</span><span class="comment">  /// Carefully document each data member.  Same as above but for not-constants.</span></div>
<div class="line"><a id="l00479" name="l00479"></a><span class="lineno">  479</span><span class="comment"></span>  Inner_class_of_cool* m_cool_ptr;</div>
<div class="line"><a id="l00480" name="l00480"></a><span class="lineno">  480</span>}; <span class="comment">// class Cool_class</span></div>
<div class="line"><a id="l00481" name="l00481"></a><span class="lineno">  481</span> </div>
<div class="line"><a id="l00482" name="l00482"></a><span class="lineno">  482</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00483" name="l00483"></a><span class="lineno">  483</span><span class="comment">/* More types (classes/structs/unions/`using` aliases/enums/enum classes) continue here if needed; including inner</span></div>
<div class="line"><a id="l00484" name="l00484"></a><span class="lineno">  484</span><span class="comment"> * classes.</span></div>
<div class="line"><a id="l00485" name="l00485"></a><span class="lineno">  485</span><span class="comment"> *</span></div>
<div class="line"><a id="l00486" name="l00486"></a><span class="lineno">  486</span><span class="comment"> * - However, leave private inner classes (like Cool_class::Inner_class_of_cool) until the end, ideally, following</span></div>
<div class="line"><a id="l00487" name="l00487"></a><span class="lineno">  487</span><span class="comment"> *   the aforementioned basic principle: API first, implementation second. */</span></div>
<div class="line"><a id="l00488" name="l00488"></a><span class="lineno">  488</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00489" name="l00489"></a><span class="lineno">  489</span><span class="comment"></span> </div>
<div class="line"><a id="l00490" name="l00490"></a><span class="lineno">  490</span><span class="comment">/**</span></div>
<div class="line"><a id="l00491" name="l00491"></a><span class="lineno">  491</span><span class="comment"> * @private</span></div>
<div class="line"><a id="l00492" name="l00492"></a><span class="lineno">  492</span><span class="comment"> *</span></div>
<div class="line"><a id="l00493" name="l00493"></a><span class="lineno">  493</span><span class="comment"> * The body of an inner class should be kept outside of its containing class, for readability.</span></div>
<div class="line"><a id="l00494" name="l00494"></a><span class="lineno">  494</span><span class="comment"> * [Sometimes C++ circular reference rules make this hard or impossible, so exceptions to this are acceptable.]</span></div>
<div class="line"><a id="l00495" name="l00495"></a><span class="lineno">  495</span><span class="comment"> *</span></div>
<div class="line"><a id="l00496" name="l00496"></a><span class="lineno">  496</span><span class="comment"> * Use @private as shown above *if and only if* the inner class is private.  This is due to a Doxygen quirk</span></div>
<div class="line"><a id="l00497" name="l00497"></a><span class="lineno">  497</span><span class="comment"> * (arguably bug).</span></div>
<div class="line"><a id="l00498" name="l00498"></a><span class="lineno">  498</span><span class="comment"> *</span></div>
<div class="line"><a id="l00499" name="l00499"></a><span class="lineno">  499</span><span class="comment"> */</span></div>
<div class="line"><a id="l00500" name="l00500"></a><span class="lineno">  500</span><span class="keyword">struct </span>Cool_class::Inner_class_of_cool</div>
<div class="line"><a id="l00501" name="l00501"></a><span class="lineno">  501</span>{</div>
<div class="line"><a id="l00502" name="l00502"></a><span class="lineno">  502</span>  <span class="comment">// [...same order of stuff as shown in Cool_class]</span></div>
<div class="line"><a id="l00503" name="l00503"></a><span class="lineno">  503</span>};</div>
<div class="line"><a id="l00504" name="l00504"></a><span class="lineno">  504</span> </div>
<div class="line"><a id="l00505" name="l00505"></a><span class="lineno">  505</span><span class="comment">// Free functions.</span></div>
<div class="line"><a id="l00506" name="l00506"></a><span class="lineno">  506</span><span class="comment"></span> </div>
<div class="line"><a id="l00507" name="l00507"></a><span class="lineno">  507</span><span class="comment">/**</span></div>
<div class="line"><a id="l00508" name="l00508"></a><span class="lineno">  508</span><span class="comment"> * Free functions aren&#39;t super-common but definitely legitimate and go in this area.  Prototype only!</span></div>
<div class="line"><a id="l00509" name="l00509"></a><span class="lineno">  509</span><span class="comment"> *</span></div>
<div class="line"><a id="l00510" name="l00510"></a><span class="lineno">  510</span><span class="comment"> * @param c1</span></div>
<div class="line"><a id="l00511" name="l00511"></a><span class="lineno">  511</span><span class="comment"> *        First operand.</span></div>
<div class="line"><a id="l00512" name="l00512"></a><span class="lineno">  512</span><span class="comment"> * @param c2</span></div>
<div class="line"><a id="l00513" name="l00513"></a><span class="lineno">  513</span><span class="comment"> *        Second operand.</span></div>
<div class="line"><a id="l00514" name="l00514"></a><span class="lineno">  514</span><span class="comment"> * @return New object that sums the operands.</span></div>
<div class="line"><a id="l00515" name="l00515"></a><span class="lineno">  515</span><span class="comment"> */</span></div>
<div class="line"><a id="l00516" name="l00516"></a><span class="lineno">  516</span>Cool_class operator+(Cool_class c1, Cool_class c2);</div>
<div class="line"><a id="l00517" name="l00517"></a><span class="lineno">  517</span><span class="comment"></span> </div>
<div class="line"><a id="l00518" name="l00518"></a><span class="lineno">  518</span><span class="comment">/**</span></div>
<div class="line"><a id="l00519" name="l00519"></a><span class="lineno">  519</span><span class="comment"> * Output of Cool_class `c` to a `basic_ostream`.</span></div>
<div class="line"><a id="l00520" name="l00520"></a><span class="lineno">  520</span><span class="comment"> * This is another free function, but this one is a template.  They can go in any order though.</span></div>
<div class="line"><a id="l00521" name="l00521"></a><span class="lineno">  521</span><span class="comment"> *</span></div>
<div class="line"><a id="l00522" name="l00522"></a><span class="lineno">  522</span><span class="comment"> * @tparam Ostream</span></div>
<div class="line"><a id="l00523" name="l00523"></a><span class="lineno">  523</span><span class="comment"> *         Document the template param type.</span></div>
<div class="line"><a id="l00524" name="l00524"></a><span class="lineno">  524</span><span class="comment"> * @param os</span></div>
<div class="line"><a id="l00525" name="l00525"></a><span class="lineno">  525</span><span class="comment"> *        Stream to write to.</span></div>
<div class="line"><a id="l00526" name="l00526"></a><span class="lineno">  526</span><span class="comment"> * @param c</span></div>
<div class="line"><a id="l00527" name="l00527"></a><span class="lineno">  527</span><span class="comment"> *        Object to write.</span></div>
<div class="line"><a id="l00528" name="l00528"></a><span class="lineno">  528</span><span class="comment"> * @return `os`.</span></div>
<div class="line"><a id="l00529" name="l00529"></a><span class="lineno">  529</span><span class="comment"> */</span></div>
<div class="line"><a id="l00530" name="l00530"></a><span class="lineno">  530</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Ostream&gt;</div>
<div class="line"><a id="l00531" name="l00531"></a><span class="lineno">  531</span>Ostream&amp; <a class="code hl_function" href="classflow_1_1cfg_1_1Option__set.html#acd1ce6e7c258d7486388915d59019880">operator&lt;&lt;</a>(Ostream&amp; os, Cool_class c);</div>
<div class="line"><a id="l00532" name="l00532"></a><span class="lineno">  532</span> </div>
<div class="line"><a id="l00533" name="l00533"></a><span class="lineno">  533</span><span class="comment">// Constants.</span></div>
<div class="line"><a id="l00534" name="l00534"></a><span class="lineno">  534</span><span class="comment"></span> </div>
<div class="line"><a id="l00535" name="l00535"></a><span class="lineno">  535</span><span class="comment">/// The mathematical `e`.  Non-member constants are fairly rare but would go in this area.</span></div>
<div class="line"><a id="l00536" name="l00536"></a><span class="lineno">  536</span><span class="comment"></span><span class="keyword">extern</span> <span class="keyword">const</span> <span class="keywordtype">float</span> S_EXPONENT;</div>
<div class="line"><a id="l00537" name="l00537"></a><span class="lineno">  537</span> </div>
<div class="line"><a id="l00538" name="l00538"></a><span class="lineno">  538</span><span class="comment">// Data.</span></div>
<div class="line"><a id="l00539" name="l00539"></a><span class="lineno">  539</span><span class="comment"></span> </div>
<div class="line"><a id="l00540" name="l00540"></a><span class="lineno">  540</span><span class="comment">/// Non-member non-constant/variable: these are arguably even more rare but would go here.</span></div>
<div class="line"><a id="l00541" name="l00541"></a><span class="lineno">  541</span><span class="comment"></span><span class="keyword">extern</span> Cool_class s_singleton_instance;</div>
<div class="line"><a id="l00542" name="l00542"></a><span class="lineno">  542</span> </div>
<div class="line"><a id="l00543" name="l00543"></a><span class="lineno">  543</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00544" name="l00544"></a><span class="lineno">  544</span><span class="comment">/* Everything above was the API!  The separation helps readability, as implementation details come later to the extent</span></div>
<div class="line"><a id="l00545" name="l00545"></a><span class="lineno">  545</span><span class="comment"> * possible.  This isn&#39;t 100% true: `private` isn&#39;t API; `private` inner classes aren&#39;t API.  Still, pretty close. */</span></div>
<div class="line"><a id="l00546" name="l00546"></a><span class="lineno">  546</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00547" name="l00547"></a><span class="lineno">  547</span> </div>
<div class="line"><a id="l00548" name="l00548"></a><span class="lineno">  548</span><span class="comment">// Template/inline implementations.  [We actually forbid explicit inlining elsewhere, but just in case, they&#39;d go here.]</span></div>
<div class="line"><a id="l00549" name="l00549"></a><span class="lineno">  549</span> </div>
<div class="line"><a id="l00550" name="l00550"></a><span class="lineno">  550</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00551" name="l00551"></a><span class="lineno">  551</span><span class="comment">/* Finally the &quot;actual code&quot; (function bodies) go here!  Recall, do NOT duplicate doc headers.</span></div>
<div class="line"><a id="l00552" name="l00552"></a><span class="lineno">  552</span><span class="comment"> * *Every* body *must* have a prototype present somewhere earlier: class/etc. methods inside class{},</span></div>
<div class="line"><a id="l00553" name="l00553"></a><span class="lineno">  553</span><span class="comment"> * free functions outside.  Then all the bodies go either here (templates, inline) or in .cpp counterpart (others). */</span></div>
<div class="line"><a id="l00554" name="l00554"></a><span class="lineno">  554</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00555" name="l00555"></a><span class="lineno">  555</span> </div>
<div class="line"><a id="l00556" name="l00556"></a><span class="lineno">  556</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Ostream&gt;</div>
<div class="line"><a id="l00557" name="l00557"></a><span class="lineno">  557</span>Ostream&amp; <a class="code hl_function" href="classflow_1_1cfg_1_1Option__set.html#acd1ce6e7c258d7486388915d59019880">operator&lt;&lt;</a>(Ostream&amp; os, Cool_class c)</div>
<div class="line"><a id="l00558" name="l00558"></a><span class="lineno">  558</span>{</div>
<div class="line"><a id="l00559" name="l00559"></a><span class="lineno">  559</span>  <span class="comment">// [...] This is a free function, but member functions (methods) go in this area as well:</span></div>
<div class="line"><a id="l00560" name="l00560"></a><span class="lineno">  560</span>}</div>
<div class="line"><a id="l00561" name="l00561"></a><span class="lineno">  561</span> </div>
<div class="line"><a id="l00562" name="l00562"></a><span class="lineno">  562</span><span class="keyword">template</span>&lt;<span class="keyword">typename</span> Some_type&gt;</div>
<div class="line"><a id="l00563" name="l00563"></a><span class="lineno">  563</span>Some_type Cool_class::cool_template_method()</div>
<div class="line"><a id="l00564" name="l00564"></a><span class="lineno">  564</span>{</div>
<div class="line"><a id="l00565" name="l00565"></a><span class="lineno">  565</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00566" name="l00566"></a><span class="lineno">  566</span>}</div>
<div class="line"><a id="l00567" name="l00567"></a><span class="lineno">  567</span> </div>
<div class="line"><a id="l00568" name="l00568"></a><span class="lineno">  568</span><span class="comment">// order.cpp follows: Illustrates above principles/shows proper ordering by example, in a counteraprt to header file:</span></div>
<div class="line"><a id="l00569" name="l00569"></a><span class="lineno">  569</span><span class="comment"></span> </div>
<div class="line"><a id="l00570" name="l00570"></a><span class="lineno">  570</span><span class="comment">/// @file</span></div>
<div class="line"><a id="l00571" name="l00571"></a><span class="lineno">  571</span><span class="comment"></span> </div>
<div class="line"><a id="l00572" name="l00572"></a><span class="lineno">  572</span><span class="preprocessor">#include &quot;[...]/order.hpp&quot;</span></div>
<div class="line"><a id="l00573" name="l00573"></a><span class="lineno">  573</span><span class="comment">// [...includes...]</span></div>
<div class="line"><a id="l00574" name="l00574"></a><span class="lineno">  574</span> </div>
<div class="line"><a id="l00575" name="l00575"></a><span class="lineno">  575</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00576" name="l00576"></a><span class="lineno">  576</span><span class="comment">/* We forego tediously describing the ordering in here.  In general, because this is not the API (unlike in .hpp),</span></div>
<div class="line"><a id="l00577" name="l00577"></a><span class="lineno">  577</span><span class="comment"> * things are more lax in here.</span></div>
<div class="line"><a id="l00578" name="l00578"></a><span class="lineno">  578</span><span class="comment"> *</span></div>
<div class="line"><a id="l00579" name="l00579"></a><span class="lineno">  579</span><span class="comment"> * - Still precede each grouping of stuff with headers.</span></div>
<div class="line"><a id="l00580" name="l00580"></a><span class="lineno">  580</span><span class="comment"> * - Typically, you will only have the following, sans doc headers (see below):</span></div>
<div class="line"><a id="l00581" name="l00581"></a><span class="lineno">  581</span><span class="comment"> *   - // Static initializers.</span></div>
<div class="line"><a id="l00582" name="l00582"></a><span class="lineno">  582</span><span class="comment"> *   - // Implementations.</span></div>
<div class="line"><a id="l00583" name="l00583"></a><span class="lineno">  583</span><span class="comment"> *</span></div>
<div class="line"><a id="l00584" name="l00584"></a><span class="lineno">  584</span><span class="comment"> * Nevertheless, there are many other things that might be necessary less commonly.  So I just list everything I can</span></div>
<div class="line"><a id="l00585" name="l00585"></a><span class="lineno">  585</span><span class="comment"> * think of, below; copy/paste into your .cpp file perhaps; delete what&#39;s not relevant to you; and proceed to fill them</span></div>
<div class="line"><a id="l00586" name="l00586"></a><span class="lineno">  586</span><span class="comment"> * out.</span></div>
<div class="line"><a id="l00587" name="l00587"></a><span class="lineno">  587</span><span class="comment"> */</span></div>
<div class="line"><a id="l00588" name="l00588"></a><span class="lineno">  588</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00589" name="l00589"></a><span class="lineno">  589</span> </div>
<div class="line"><a id="l00590" name="l00590"></a><span class="lineno">  590</span><span class="comment">// Static initializers.  [Common: Initializations of constants, static data, etc. declared/documented in .hpp.]</span></div>
<div class="line"><a id="l00591" name="l00591"></a><span class="lineno">  591</span> </div>
<div class="line"><a id="l00592" name="l00592"></a><span class="lineno">  592</span><span class="comment">// Local types.  [Rare: Types used only in this .cpp.  This is rare in C++, but who knows?]</span></div>
<div class="line"><a id="l00593" name="l00593"></a><span class="lineno">  593</span> </div>
<div class="line"><a id="l00594" name="l00594"></a><span class="lineno">  594</span><span class="comment">// Local functions.  [Rare: Prototypes *and doc headers* ONLY!  `static` non-member functions are rare in C++.]</span></div>
<div class="line"><a id="l00595" name="l00595"></a><span class="lineno">  595</span> </div>
<div class="line"><a id="l00596" name="l00596"></a><span class="lineno">  596</span><span class="comment">// Local constants and their initializers.  [Rare: Constants used only in this .cpp.  Again, rare in C++.]</span></div>
<div class="line"><a id="l00597" name="l00597"></a><span class="lineno">  597</span> </div>
<div class="line"><a id="l00598" name="l00598"></a><span class="lineno">  598</span><span class="comment">// Local data and their initializers.  [Ditto.]</span></div>
<div class="line"><a id="l00599" name="l00599"></a><span class="lineno">  599</span> </div>
<div class="line"><a id="l00600" name="l00600"></a><span class="lineno">  600</span><span class="comment">// Implementations.  [Common: The bodies of functions declared in .hpp and (uncommonly) local ones from just above.]</span></div>
<div class="line"><a id="l00601" name="l00601"></a><span class="lineno">  601</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00602" name="l00602"></a><span class="lineno">  602</span><span class="comment">/* It also helps, when there are 2+ classes/structs/etc. with bodies, to have a separate section for each:</span></div>
<div class="line"><a id="l00603" name="l00603"></a><span class="lineno">  603</span><span class="comment"> *   // Cool_class implementations.</span></div>
<div class="line"><a id="l00604" name="l00604"></a><span class="lineno">  604</span><span class="comment"> *   // Cool_class::Inner_class_of_cool implementations.</span></div>
<div class="line"><a id="l00605" name="l00605"></a><span class="lineno">  605</span><span class="comment"> * It&#39;s left to your discretion however. */</span></div>
<div class="line"><a id="l00606" name="l00606"></a><span class="lineno">  606</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00607" name="l00607"></a><span class="lineno">  607</span> </div>
<div class="line"><a id="l00608" name="l00608"></a><span class="lineno">  608</span><span class="comment">// -- STYLE GUIDE: Spacing and indentation --</span></div>
<div class="line"><a id="l00609" name="l00609"></a><span class="lineno">  609</span> </div>
<div class="line"><a id="l00610" name="l00610"></a><span class="lineno">  610</span><span class="comment">/* Beyond the basics (no tab characters; 120 columns per line; indent level = 2) there are various conventions</span></div>
<div class="line"><a id="l00611" name="l00611"></a><span class="lineno">  611</span><span class="comment"> * regarding white-space and indentation.  Many style guides omit some of these details, and inconsistency is common.</span></div>
<div class="line"><a id="l00612" name="l00612"></a><span class="lineno">  612</span><span class="comment"> * Please follow the following rules as shown by example. */</span></div>
<div class="line"><a id="l00613" name="l00613"></a><span class="lineno">  613</span> </div>
<div class="line"><a id="l00614" name="l00614"></a><span class="lineno">  614</span><span class="keyword">namespace </span>flow::submodule</div>
<div class="line"><a id="l00615" name="l00615"></a><span class="lineno">  615</span>{</div>
<div class="line"><a id="l00616" name="l00616"></a><span class="lineno">  616</span> </div>
<div class="line"><a id="l00617" name="l00617"></a><span class="lineno">  617</span><span class="comment">/* A new { block } *always* means new indentation level, *except* due to being within namespace {}.</span></div>
<div class="line"><a id="l00618" name="l00618"></a><span class="lineno">  618</span><span class="comment"> * Nested namespaces themselves shall use C++17 syntax, wherein one writes `namespace a::b::c` instead of</span></div>
<div class="line"><a id="l00619" name="l00619"></a><span class="lineno">  619</span><span class="comment"> * `namespace a { namespace b { namespace c`.  This is shown above.</span></div>
<div class="line"><a id="l00620" name="l00620"></a><span class="lineno">  620</span><span class="comment"> * (Even if 1 file declares members of 2+ different namespaces, one shall declare each namespace, no matter its</span></div>
<div class="line"><a id="l00621" name="l00621"></a><span class="lineno">  621</span><span class="comment"> * depth level, using `namespace a::b::c` syntax, where `a` is always an outer namespace.)</span></div>
<div class="line"><a id="l00622" name="l00622"></a><span class="lineno">  622</span><span class="comment"> * The actual members declared within a given namespace shall begin indentation at column 0, as seen in the following</span></div>
<div class="line"><a id="l00623" name="l00623"></a><span class="lineno">  623</span><span class="comment"> * `cool_method()` declaration.</span></div>
<div class="line"><a id="l00624" name="l00624"></a><span class="lineno">  624</span><span class="comment"> * [Rationale: The latter avoids losing one indent-level of real estate on practically every line of code with little</span></div>
<div class="line"><a id="l00625" name="l00625"></a><span class="lineno">  625</span><span class="comment"> * benefit.</span></div>
<div class="line"><a id="l00626" name="l00626"></a><span class="lineno">  626</span><span class="comment"> * @todo Since we are now on C++17, and hence mandate the use of `namespace a::b::c {}` syntax, consider updating style</span></div>
<div class="line"><a id="l00627" name="l00627"></a><span class="lineno">  627</span><span class="comment"> * guide -- and all code -- to indent properly even inside namespaces, while continuing to demand the use of</span></div>
<div class="line"><a id="l00628" name="l00628"></a><span class="lineno">  628</span><span class="comment"> * `namespace a::b::c` syntax.  One level on indent shall be lost by this, but since with the C++17 syntax it *is*</span></div>
<div class="line"><a id="l00629" name="l00629"></a><span class="lineno">  629</span><span class="comment"> * at most just the 1 indent-level -- as opposed to typically 2 or more before C++17 syntax -- the prettier and more</span></div>
<div class="line"><a id="l00630" name="l00630"></a><span class="lineno">  630</span><span class="comment"> * consistent-overall indentation may be worth it.] */</span></div>
<div class="line"><a id="l00631" name="l00631"></a><span class="lineno">  631</span> </div>
<div class="line"><a id="l00632" name="l00632"></a><span class="lineno">  632</span><span class="keywordtype">void</span> Cool_class::cool_method(<span class="keywordtype">int</span> a, <span class="keywordtype">int</span> b)</div>
<div class="line"><a id="l00633" name="l00633"></a><span class="lineno">  633</span>{</div>
<div class="line"><a id="l00634" name="l00634"></a><span class="lineno">  634</span>  <span class="keywordflow">if</span> (a &lt; b)</div>
<div class="line"><a id="l00635" name="l00635"></a><span class="lineno">  635</span>  {</div>
<div class="line"><a id="l00636" name="l00636"></a><span class="lineno">  636</span>    <span class="comment">/* *Always* use {} around one-statement flow-control bodies even when unnecessary, such as here.</span></div>
<div class="line"><a id="l00637" name="l00637"></a><span class="lineno">  637</span><span class="comment">     * [Rationale: Doing otherwise leads to frequent maintenance bugs.  Also this helps simplify rule set.] */</span></div>
<div class="line"><a id="l00638" name="l00638"></a><span class="lineno">  638</span>    <span class="keywordflow">return</span>;</div>
<div class="line"><a id="l00639" name="l00639"></a><span class="lineno">  639</span>  }</div>
<div class="line"><a id="l00640" name="l00640"></a><span class="lineno">  640</span> </div>
<div class="line"><a id="l00641" name="l00641"></a><span class="lineno">  641</span>  <span class="comment">// else</span></div>
<div class="line"><a id="l00642" name="l00642"></a><span class="lineno">  642</span>  <span class="comment">// [^-- Little markers like this are common in Flow.  Not mandatory but consider doing same.]</span></div>
<div class="line"><a id="l00643" name="l00643"></a><span class="lineno">  643</span> </div>
<div class="line"><a id="l00644" name="l00644"></a><span class="lineno">  644</span>  <span class="comment">/* - *Always* place spaces around binary/ternary operators (`a * b`, `?:`), never in front of unary ones (`-a`).</span></div>
<div class="line"><a id="l00645" name="l00645"></a><span class="lineno">  645</span><span class="comment">   * - *Always* use `()` to enforce order of operations, even when redundant to build-in language rules!</span></div>
<div class="line"><a id="l00646" name="l00646"></a><span class="lineno">  646</span><span class="comment">   *   [Rationale: It hugely helps avoid bugs.  It also helps reassure reader of the coder&#39;s intent.]</span></div>
<div class="line"><a id="l00647" name="l00647"></a><span class="lineno">  647</span><span class="comment">   *   - Exception: The `.`, `-&gt;`, `*`, `&amp;` operators.  They&#39;re so high-priority that there&#39;s really no need.</span></div>
<div class="line"><a id="l00648" name="l00648"></a><span class="lineno">  648</span><span class="comment">   *     Same for function calls `func()`.</span></div>
<div class="line"><a id="l00649" name="l00649"></a><span class="lineno">  649</span><span class="comment">   *   - Exception: The `=` and other assignment ops.  They&#39;re so low-priority that there&#39;s really no need.</span></div>
<div class="line"><a id="l00650" name="l00650"></a><span class="lineno">  650</span><span class="comment">   * - If an expression is long or complicated, use your judgment to optionally make it into multiple lines for clarity.</span></div>
<div class="line"><a id="l00651" name="l00651"></a><span class="lineno">  651</span><span class="comment">   *   - Use column-lined-up intra-expression indentation as shown here.</span></div>
<div class="line"><a id="l00652" name="l00652"></a><span class="lineno">  652</span><span class="comment">   *   - If an operator (in this case `?` and `:` and `&amp;&amp;`) can go either at the end of line N or start of line (N + 1),</span></div>
<div class="line"><a id="l00653" name="l00653"></a><span class="lineno">  653</span><span class="comment">   *     prefer the latter.</span></div>
<div class="line"><a id="l00654" name="l00654"></a><span class="lineno">  654</span><span class="comment">   *     [Rationale: There are tedious pros/cons.  I chose this for consistency, but the other way would&#39;ve been OK.] */</span></div>
<div class="line"><a id="l00655" name="l00655"></a><span class="lineno">  655</span>  a = b = (m_other_flag || (m_flag</div>
<div class="line"><a id="l00656" name="l00656"></a><span class="lineno">  656</span>                            &amp;&amp; (((-a) * rnd()) &gt; 3)))</div>
<div class="line"><a id="l00657" name="l00657"></a><span class="lineno">  657</span>            ? (m_val1.m_sub_val + cool_func1())</div>
<div class="line"><a id="l00658" name="l00658"></a><span class="lineno">  658</span>            : (m_val2_ptr-&gt;m_sub_val + cool_func2);</div>
<div class="line"><a id="l00659" name="l00659"></a><span class="lineno">  659</span> </div>
<div class="line"><a id="l00660" name="l00660"></a><span class="lineno">  660</span>  <span class="comment">/* A separate `statement;` per stack variable declaration, even when you can combine them.</span></div>
<div class="line"><a id="l00661" name="l00661"></a><span class="lineno">  661</span><span class="comment">   * [Rationale: `int* a, b;` misleads one into thinking `b` is a pointer like `a`.  And simplicity+consistency.] */</span></div>
<div class="line"><a id="l00662" name="l00662"></a><span class="lineno">  662</span>  <span class="keywordtype">int</span>* a;</div>
<div class="line"><a id="l00663" name="l00663"></a><span class="lineno">  663</span>  <span class="keywordtype">int</span> b;</div>
<div class="line"><a id="l00664" name="l00664"></a><span class="lineno">  664</span>  <span class="keywordtype">float</span>&amp; c = m_floatie; <span class="comment">// The type is `float&amp;`; the value is `c`.  Do NOT do: `float &amp;c;`.</span></div>
<div class="line"><a id="l00665" name="l00665"></a><span class="lineno">  665</span>  <span class="keywordtype">float</span>* d = m_ptr; <span class="comment">// Same.  Type is `float*` (not `float *`); value is `d`.</span></div>
<div class="line"><a id="l00666" name="l00666"></a><span class="lineno">  666</span> </div>
<div class="line"><a id="l00667" name="l00667"></a><span class="lineno">  667</span>  <span class="comment">// `const` ordering in type names:</span></div>
<div class="line"><a id="l00668" name="l00668"></a><span class="lineno">  668</span>  <span class="keyword">const</span> <span class="keywordtype">char</span>* str; <span class="comment">// This is fine; it&#39;s so typical out in the world that we couldn&#39;t possibly disallow it.</span></div>
<div class="line"><a id="l00669" name="l00669"></a><span class="lineno">  669</span>  <span class="keywordtype">char</span> <span class="keyword">const</span> * str; <span class="comment">// This is arguably better; reading backwards is useful: pointer to / const / char.</span></div>
<div class="line"><a id="l00670" name="l00670"></a><span class="lineno">  670</span>  <span class="comment">// What if you want the pointed-to value to be immutable AND the pointer *itself*?</span></div>
<div class="line"><a id="l00671" name="l00671"></a><span class="lineno">  671</span>  <span class="keywordtype">char</span> <span class="keyword">const</span> * <span class="keyword">const</span> str; <span class="comment">// Read R2L: const / pointer to / const / char.</span></div>
<div class="line"><a id="l00672" name="l00672"></a><span class="lineno">  672</span><span class="preprocessor">#if 0 </span><span class="comment">// Don&#39;t do this when it gets complex with multiple consts; use the R2L ordering to avoid confusion (prev line).</span></div>
<div class="line"><a id="l00673" name="l00673"></a><span class="lineno">  673</span>  <span class="keyword">const</span> <span class="keywordtype">char</span> * <span class="keyword">const</span> str; <span class="comment">// Don&#39;t do this.</span></div>
<div class="line"><a id="l00674" name="l00674"></a><span class="lineno">  674</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00675" name="l00675"></a><span class="lineno">  675</span> </div>
<div class="line"><a id="l00676" name="l00676"></a><span class="lineno">  676</span>  <span class="comment">/* Logging is very common and has some tiny subtleties to improve readability.</span></div>
<div class="line"><a id="l00677" name="l00677"></a><span class="lineno">  677</span><span class="comment">   * Intra-message indentation is to be avoided.  [Rationale: Just cosmetics.  It looks nicer.] */</span></div>
<div class="line"><a id="l00678" name="l00678"></a><span class="lineno">  678</span>  <a class="code hl_define" href="log_8hpp.html#a626c7dc4d3b4dc0b32a8aac8624d66bc">FLOW_LOG_WARNING</a>(<span class="stringliteral">&quot;In logging/diagnostics/etc. place [&quot;</span> &lt;&lt; a &lt;&lt; <span class="stringliteral">&quot;] around variables.  &quot;</span></div>
<div class="line"><a id="l00679" name="l00679"></a><span class="lineno">  679</span>                   <span class="stringliteral">&quot;Like comments, use sentence-like things, start with capital, end with period/etc. and 1-2 spaces &quot;</span></div>
<div class="line"><a id="l00680" name="l00680"></a><span class="lineno">  680</span>                   <span class="stringliteral">&quot;unless end of the message.  Optional but highly encouraged.&quot;</span>);</div>
<div class="line"><a id="l00681" name="l00681"></a><span class="lineno">  681</span>  <span class="comment">// But when there are 2+ arguments to the call, add intra-arg indentation back in.</span></div>
<div class="line"><a id="l00682" name="l00682"></a><span class="lineno">  682</span>  <a class="code hl_define" href="log_8hpp.html#a5daa2b6d16edea74bb8bddc75f7fb801">FLOW_LOG_WITHOUT_CHECKING</a></div>
<div class="line"><a id="l00683" name="l00683"></a><span class="lineno">  683</span>    (Sev::S_WARNING,</div>
<div class="line"><a id="l00684" name="l00684"></a><span class="lineno">  684</span>     <span class="stringliteral">&quot;Async_file_logger [&quot;</span> &lt;&lt; <span class="keyword">this</span> &lt;&lt; <span class="stringliteral">&quot;] @ [&quot;</span> &lt;&lt; m_log_path &lt;&lt; <span class="stringliteral">&quot;]: do_log() just tried to log msg when file stream &quot;</span></div>
<div class="line"><a id="l00685" name="l00685"></a><span class="lineno">  685</span>       <span class="stringliteral">&quot;was in good state, but now file stream is in bad state, probably because the write failed.  &quot;</span></div>
<div class="line"><a id="l00686" name="l00686"></a><span class="lineno">  686</span>       <span class="stringliteral">&quot;Giving up on that log message.  Will retry file stream for next message.&quot;</span>);</div>
<div class="line"><a id="l00687" name="l00687"></a><span class="lineno">  687</span>  <span class="comment">// ^-- Note indentation in 2nd arg, so it&#39;s clear at glance there are 2 args and not 4.</span></div>
<div class="line"><a id="l00688" name="l00688"></a><span class="lineno">  688</span> </div>
<div class="line"><a id="l00689" name="l00689"></a><span class="lineno">  689</span>  <span class="comment">// Personal discretion about when to break-and-indent, vs. when to line up by column.</span></div>
<div class="line"><a id="l00690" name="l00690"></a><span class="lineno">  690</span>  <a class="code hl_define" href="log_8hpp.html#a5daa2b6d16edea74bb8bddc75f7fb801">FLOW_LOG_WITHOUT_CHECKING</a>(Sev::S_WARNING, <span class="stringliteral">&quot;Some message with stuff in it.&quot;</span>); <span class="comment">// Cool.</span></div>
<div class="line"><a id="l00691" name="l00691"></a><span class="lineno">  691</span>  <a class="code hl_define" href="log_8hpp.html#a5daa2b6d16edea74bb8bddc75f7fb801">FLOW_LOG_WITHOUT_CHECKING</a>(Sev::S_WARNING,</div>
<div class="line"><a id="l00692" name="l00692"></a><span class="lineno">  692</span>                            <span class="stringliteral">&quot;Some message with stuff in it.&quot;</span>); <span class="comment">// Cool as well.</span></div>
<div class="line"><a id="l00693" name="l00693"></a><span class="lineno">  693</span>  <a class="code hl_define" href="log_8hpp.html#a5daa2b6d16edea74bb8bddc75f7fb801">FLOW_LOG_WITHOUT_CHECKING</a></div>
<div class="line"><a id="l00694" name="l00694"></a><span class="lineno">  694</span>    (Sev::S_WARNING, <span class="stringliteral">&quot;Some message with stuff in it.&quot;</span>); <span class="comment">// Perfectly cool also.</span></div>
<div class="line"><a id="l00695" name="l00695"></a><span class="lineno">  695</span>  <a class="code hl_define" href="log_8hpp.html#a5daa2b6d16edea74bb8bddc75f7fb801">FLOW_LOG_WITHOUT_CHECKING</a></div>
<div class="line"><a id="l00696" name="l00696"></a><span class="lineno">  696</span>    (Sev::S_WARNING,</div>
<div class="line"><a id="l00697" name="l00697"></a><span class="lineno">  697</span>     <span class="stringliteral">&quot;Some message with stuff in it.&quot;</span>); <span class="comment">// Excessive here (since it&#39;s short), probably, but it&#39;s also fine.</span></div>
<div class="line"><a id="l00698" name="l00698"></a><span class="lineno">  698</span> </div>
<div class="line"><a id="l00699" name="l00699"></a><span class="lineno">  699</span>  <span class="comment">/* Finally, when assembling long strings (such as for logging, or inside FLOW_LOG_...()) via `ostream`,</span></div>
<div class="line"><a id="l00700" name="l00700"></a><span class="lineno">  700</span><span class="comment">   * it is OK to somewhat break other conventions for readability.  To quote real code: */</span></div>
<div class="line"><a id="l00701" name="l00701"></a><span class="lineno">  701</span>  os</div>
<div class="line"><a id="l00702" name="l00702"></a><span class="lineno">  702</span>    &lt;&lt;</div>
<div class="line"><a id="l00703" name="l00703"></a><span class="lineno">  703</span>    <span class="stringliteral">&quot;--- Basic socket state ---\n&quot;</span></div>
<div class="line"><a id="l00704" name="l00704"></a><span class="lineno">  704</span>    <span class="stringliteral">&quot;Internal state: [&quot;</span> &lt;&lt; m_int_state_str &lt;&lt; <span class="stringliteral">&quot;].\n&quot;</span></div>
<div class="line"><a id="l00705" name="l00705"></a><span class="lineno">  705</span>    <span class="stringliteral">&quot;Client or server: [&quot;</span> &lt;&lt; (m_is_active_connect ? <span class="stringliteral">&quot;client&quot;</span> : <span class="stringliteral">&quot;server&quot;</span>) &lt;&lt; <span class="stringliteral">&quot;].\n&quot;</span></div>
<div class="line"><a id="l00706" name="l00706"></a><span class="lineno">  706</span>    <span class="comment">// Also visible below in the options but show it separately for convenience.</span></div>
<div class="line"><a id="l00707" name="l00707"></a><span class="lineno">  707</span>    <span class="stringliteral">&quot;Reliability mode: [&quot;</span> &lt;&lt; (m_sock_opts.m_st_rexmit_on ? <span class="stringliteral">&quot;reliable/rexmit on&quot;</span> : <span class="stringliteral">&quot;unreliable/rexmit off&quot;</span>) &lt;&lt; <span class="stringliteral">&quot;].\n&quot;</span></div>
<div class="line"><a id="l00708" name="l00708"></a><span class="lineno">  708</span>    <span class="stringliteral">&quot;--- Buffers/queues/lists ----\n&quot;</span></div>
<div class="line"><a id="l00709" name="l00709"></a><span class="lineno">  709</span>    <span class="stringliteral">&quot;Receive window (free space): [&quot;</span> &lt;&lt; m_rcv_wnd &lt;&lt; <span class="stringliteral">&quot;]\n&quot;</span></div>
<div class="line"><a id="l00710" name="l00710"></a><span class="lineno">  710</span>    <span class="stringliteral">&quot;  = limit\n&quot;</span></div>
<div class="line"><a id="l00711" name="l00711"></a><span class="lineno">  711</span>    <span class="stringliteral">&quot;  - Receive buffer size: [&quot;</span> &lt;&lt; m_rcv_buf_size &lt;&lt; <span class="stringliteral">&quot;]\n&quot;</span></div>
<div class="line"><a id="l00712" name="l00712"></a><span class="lineno">  712</span>    <span class="stringliteral">&quot;  - reassembly queue total data size: [&quot;</span> &lt;&lt; m_rcv_reassembly_q_data_size &lt;&lt; <span class="stringliteral">&quot;] (0 if rexmit off)\n&quot;</span></div>
<div class="line"><a id="l00713" name="l00713"></a><span class="lineno">  713</span>    <span class="stringliteral">&quot;      &quot;</span> &lt;&lt; (m_sock_opts.m_st_rexmit_on ? <span class="stringliteral">&quot;Reassembly queue&quot;</span> : <span class="stringliteral">&quot;Dupe check list&quot;</span>) &lt;&lt;</div>
<div class="line"><a id="l00714" name="l00714"></a><span class="lineno">  714</span>    <span class="stringliteral">&quot; length: [&quot;</span> &lt;&lt; m_rcv_packets_with_gaps &lt;&lt; <span class="stringliteral">&quot;].\n&quot;</span></div>
<div class="line"><a id="l00715" name="l00715"></a><span class="lineno">  715</span>    <span class="stringliteral">&quot;  Last advertised: [&quot;</span> &lt;&lt; m_rcv_wnd_last_advertised &lt;&lt; <span class="stringliteral">&quot;].\n&quot;</span>;</div>
<div class="line"><a id="l00716" name="l00716"></a><span class="lineno">  716</span>  <span class="comment">/* ^-- Note that this combines compiler-concatenated string-literals and trailing &lt;&lt; (the latter being discouraged</span></div>
<div class="line"><a id="l00717" name="l00717"></a><span class="lineno">  717</span><span class="comment">   * elsewhere in this guide) for readability, so the final output is somewhat easier to visualize. */</span></div>
<div class="line"><a id="l00718" name="l00718"></a><span class="lineno">  718</span> </div>
<div class="line"><a id="l00719" name="l00719"></a><span class="lineno">  719</span>  <span class="comment">/* Lambdas are HEAVILY used yet very unusual-looking vs. rest of C++.  Formatting decisions can be challenging.</span></div>
<div class="line"><a id="l00720" name="l00720"></a><span class="lineno">  720</span><span class="comment">   * Use the following conventions. */</span></div>
<div class="line"><a id="l00721" name="l00721"></a><span class="lineno">  721</span> </div>
<div class="line"><a id="l00722" name="l00722"></a><span class="lineno">  722</span>  <span class="comment">/* A lambda can (typically SHOULD NOT but use discretion!) begin anywhere, in any expression, even though it</span></div>
<div class="line"><a id="l00723" name="l00723"></a><span class="lineno">  723</span><span class="comment">   * represents a function/closure thing.  In this case it begins smack in the middle of a regular function call inside</span></div>
<div class="line"><a id="l00724" name="l00724"></a><span class="lineno">  724</span><span class="comment">   * another function call.</span></div>
<div class="line"><a id="l00725" name="l00725"></a><span class="lineno">  725</span><span class="comment">   *   - Always include a [capture section], even if empty.</span></div>
<div class="line"><a id="l00726" name="l00726"></a><span class="lineno">  726</span><span class="comment">   *   - Always include an (args list), even if empty.</span></div>
<div class="line"><a id="l00727" name="l00727"></a><span class="lineno">  727</span><span class="comment">   *     - Always include an explicit `-&gt; type` -- even if it can be auto-figured-out -- on same line as (args list).</span></div>
<div class="line"><a id="l00728" name="l00728"></a><span class="lineno">  728</span><span class="comment">   *       - Except if the type would have been `void`; then omit it.</span></div>
<div class="line"><a id="l00729" name="l00729"></a><span class="lineno">  729</span><span class="comment">   *</span></div>
<div class="line"><a id="l00730" name="l00730"></a><span class="lineno">  730</span><span class="comment">   * [Rationale: It&#39;s quite subjective, but I&#39;ve (ygoldfel) found this leads to visual pattern recognition of a lambda;</span></div>
<div class="line"><a id="l00731" name="l00731"></a><span class="lineno">  731</span><span class="comment">   * yet without excessive amounts of boiler-plate characters.  Plus, it creates discipline to carefully craft</span></div>
<div class="line"><a id="l00732" name="l00732"></a><span class="lineno">  732</span><span class="comment">   * each lambda as opposed to &quot;shooting from the hip&quot; as scripting languages like JavaScript encourage.] */</span></div>
<div class="line"><a id="l00733" name="l00733"></a><span class="lineno">  733</span>  sched_task</div>
<div class="line"><a id="l00734" name="l00734"></a><span class="lineno">  734</span>    = <a class="code hl_function" href="namespaceflow_1_1util.html#aad8c8f7335eb892350dc386cb4be397e">util::schedule_task_at</a>(get_logger(), wait_until, &amp;task_engine,</div>
<div class="line"><a id="l00735" name="l00735"></a><span class="lineno">  735</span>                             m_make_serial.wrap <span class="comment">// Lambda begins as the arg to this function call:</span></div>
<div class="line"><a id="l00736" name="l00736"></a><span class="lineno">  736</span>                               ([<span class="keyword">this</span>, timeout_state, on_result, would_block_ret_val, event_set]</div>
<div class="line"><a id="l00737" name="l00737"></a><span class="lineno">  737</span>                                (<span class="keywordtype">bool</span>) -&gt; <span class="keywordtype">bool</span></div>
<div class="line"><a id="l00738" name="l00738"></a><span class="lineno">  738</span>  {</div>
<div class="line"><a id="l00739" name="l00739"></a><span class="lineno">  739</span>    <span class="comment">/* *Main point*: The lambda&#39;s { body } *always* starts on the same column as the current *statement*.</span></div>
<div class="line"><a id="l00740" name="l00740"></a><span class="lineno">  740</span><span class="comment">     * This is regardless of there the lambda itself -- the [captures] -- started.</span></div>
<div class="line"><a id="l00741" name="l00741"></a><span class="lineno">  741</span><span class="comment">     * [Rationale: This preserves a sane indentation level! A { body } that starts on some column in the middle of</span></div>
<div class="line"><a id="l00742" name="l00742"></a><span class="lineno">  742</span><span class="comment">     * a line is just a nightmare of inconsistency and maintenance.] */</span></div>
<div class="line"><a id="l00743" name="l00743"></a><span class="lineno">  743</span> </div>
<div class="line"><a id="l00744" name="l00744"></a><span class="lineno">  744</span>    FLOW_LOG_TRACE(<span class="stringliteral">&quot;[User event loop] &quot;</span></div>
<div class="line"><a id="l00745" name="l00745"></a><span class="lineno">  745</span>                   <span class="stringliteral">&quot;Timeout fired for async op [&quot;</span> &lt;&lt; event_set &lt;&lt; <span class="stringliteral">&quot;]; clean up and report to user.&quot;</span>);</div>
<div class="line"><a id="l00746" name="l00746"></a><span class="lineno">  746</span> </div>
<div class="line"><a id="l00747" name="l00747"></a><span class="lineno">  747</span>    Error_code dummy_prevents_throw;</div>
<div class="line"><a id="l00748" name="l00748"></a><span class="lineno">  748</span>    event_set-&gt;async_wait_finish(&amp;dummy_prevents_throw);</div>
<div class="line"><a id="l00749" name="l00749"></a><span class="lineno">  749</span> </div>
<div class="line"><a id="l00750" name="l00750"></a><span class="lineno">  750</span>    return true; <span class="comment">// Always use an explicit `return x;`, if you must return a value.  No funny lambda business.</span></div>
<div class="line"><a id="l00751" name="l00751"></a><span class="lineno">  751</span>  })); <span class="comment">// timer.async_wait() callback.</span></div>
<div class="line"><a id="l00752" name="l00752"></a><span class="lineno">  752</span> </div>
<div class="line"><a id="l00753" name="l00753"></a><span class="lineno">  753</span><span class="preprocessor">#if 0 </span><span class="comment">// NO.  Do not start the body lined up like this.  Line it up with the statement, as shown above.</span></div>
<div class="line"><a id="l00754" name="l00754"></a><span class="lineno">  754</span>  sched_task</div>
<div class="line"><a id="l00755" name="l00755"></a><span class="lineno">  755</span>    = <a class="code hl_function" href="namespaceflow_1_1util.html#aad8c8f7335eb892350dc386cb4be397e">util::schedule_task_at</a>(get_logger(), wait_until, &amp;task_engine,</div>
<div class="line"><a id="l00756" name="l00756"></a><span class="lineno">  756</span>                             m_make_serial.wrap <span class="comment">// Lambda begins as the arg to this function call:</span></div>
<div class="line"><a id="l00757" name="l00757"></a><span class="lineno">  757</span>                               ([<span class="keyword">this</span>, timeout_state, on_result, would_block_ret_val, event_set]</div>
<div class="line"><a id="l00758" name="l00758"></a><span class="lineno">  758</span>                                (<span class="keywordtype">bool</span>) -&gt; <span class="keywordtype">bool</span></div>
<div class="line"><a id="l00759" name="l00759"></a><span class="lineno">  759</span>                                {</div>
<div class="line"><a id="l00760" name="l00760"></a><span class="lineno">  760</span>                                  <span class="comment">// [...Body...]</span></div>
<div class="line"><a id="l00761" name="l00761"></a><span class="lineno">  761</span>                                })); <span class="comment">// timer.async_wait() callback.</span></div>
<div class="line"><a id="l00762" name="l00762"></a><span class="lineno">  762</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00763" name="l00763"></a><span class="lineno">  763</span> </div>
<div class="line"><a id="l00764" name="l00764"></a><span class="lineno">  764</span>  <span class="comment">// You may put lambda { body } on same line as the rest of it -- for VERY short bodies like this.</span></div>
<div class="line"><a id="l00765" name="l00765"></a><span class="lineno">  765</span>  func([<span class="keyword">this</span>](){ hooray(m_data_member); });</div>
<div class="line"><a id="l00766" name="l00766"></a><span class="lineno">  766</span> </div>
<div class="line"><a id="l00767" name="l00767"></a><span class="lineno">  767</span>  <span class="comment">// While in-line lambdas are allowed (as just above), they *must* then be the last part of the statement.</span></div>
<div class="line"><a id="l00768" name="l00768"></a><span class="lineno">  768</span> </div>
<div class="line"><a id="l00769" name="l00769"></a><span class="lineno">  769</span>  func(1, 2, [<span class="keyword">this</span>](){ hooray(m_data_member); }); <span class="comment">// A bit ugly arguably, but this is allowed.</span></div>
<div class="line"><a id="l00770" name="l00770"></a><span class="lineno">  770</span><span class="preprocessor">#if 0 </span><span class="comment">// NOT allowed.  There is more &quot;stuff&quot; after the lambda, so don&#39;t in-line it.</span></div>
<div class="line"><a id="l00771" name="l00771"></a><span class="lineno">  771</span>  func([<span class="keyword">this</span>](){ <span class="keywordflow">return</span> m_data_member; }, 1, 2);</div>
<div class="line"><a id="l00772" name="l00772"></a><span class="lineno">  772</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00773" name="l00773"></a><span class="lineno">  773</span>  <span class="comment">// In that case save it in a variable.</span></div>
<div class="line"><a id="l00774" name="l00774"></a><span class="lineno">  774</span>  <span class="keyword">const</span> <span class="keyword">auto</span> lambda = [<span class="keyword">this</span>](){ hooray(m_data_member); };</div>
<div class="line"><a id="l00775" name="l00775"></a><span class="lineno">  775</span>  func(lambda, 1, 2);</div>
<div class="line"><a id="l00776" name="l00776"></a><span class="lineno">  776</span> </div>
<div class="line"><a id="l00777" name="l00777"></a><span class="lineno">  777</span>  <span class="comment">/* To be clear, in general, if an in-line lambda is looking even a little obnoxious, err on the side of</span></div>
<div class="line"><a id="l00778" name="l00778"></a><span class="lineno">  778</span><span class="comment">   * &quot;just save it in a `const auto`,&quot; as shown above. */</span></div>
<div class="line"><a id="l00779" name="l00779"></a><span class="lineno">  779</span>} <span class="comment">// Cool_class::cool_method() [&lt;-- Note the convention for terminating `}` comment of non-tiny function bodies.]</span></div>
<div class="line"><a id="l00780" name="l00780"></a><span class="lineno">  780</span> </div>
<div class="line"><a id="l00781" name="l00781"></a><span class="lineno">  781</span><span class="comment">/* [Optional but strongly encouraged:] If a function takes 1 or more function-style arguments (which</span></div>
<div class="line"><a id="l00782" name="l00782"></a><span class="lineno">  782</span><span class="comment"> * in practice end up being created from lambdas, usually), put them at the end of the function&#39;s arg list.</span></div>
<div class="line"><a id="l00783" name="l00783"></a><span class="lineno">  783</span><span class="comment"> * [Rationale: It helps make it possible to in-line lambdas in most situations, if desired.] */</span></div>
<div class="line"><a id="l00784" name="l00784"></a><span class="lineno">  784</span><span class="keywordtype">void</span> Cool_class::cool_method2(log::Logger* logger, <span class="keyword">const</span> <a class="code hl_class" href="classflow_1_1Function.html">flow::Function</a>&lt;<span class="keywordtype">void</span> ()&gt;&amp; on_completion_func)</div>
<div class="line"><a id="l00785" name="l00785"></a><span class="lineno">  785</span>{</div>
<div class="line"><a id="l00786" name="l00786"></a><span class="lineno">  786</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00787" name="l00787"></a><span class="lineno">  787</span>  cool_method2(logger, [<span class="keyword">this</span>]()</div>
<div class="line"><a id="l00788" name="l00788"></a><span class="lineno">  788</span>  {</div>
<div class="line"><a id="l00789" name="l00789"></a><span class="lineno">  789</span>    hooray(m_data_member);</div>
<div class="line"><a id="l00790" name="l00790"></a><span class="lineno">  790</span>  }); <span class="comment">// Can always in-line it, because it&#39;s the last arg to cool_method2(), so nothing can follow it.</span></div>
<div class="line"><a id="l00791" name="l00791"></a><span class="lineno">  791</span>  <span class="comment">// [...]</span></div>
<div class="line"><a id="l00792" name="l00792"></a><span class="lineno">  792</span>}</div>
<div class="line"><a id="l00793" name="l00793"></a><span class="lineno">  793</span> </div>
<div class="line"><a id="l00794" name="l00794"></a><span class="lineno">  794</span>} <span class="comment">// namespace flow::submodule</span></div>
<div class="line"><a id="l00795" name="l00795"></a><span class="lineno">  795</span> </div>
<div class="line"><a id="l00796" name="l00796"></a><span class="lineno">  796</span><span class="comment">// Label-type thingies (ctor init; public/private/protected; `case X:`/`default:`; the rare actual goto label):</span></div>
<div class="line"><a id="l00797" name="l00797"></a><span class="lineno">  797</span><span class="keyword">class </span>X</div>
<div class="line"><a id="l00798" name="l00798"></a><span class="lineno">  798</span>{</div>
<div class="line"><a id="l00799" name="l00799"></a><span class="lineno">  799</span><span class="keyword">public</span>: <span class="comment">// Label starts on same column as preceding thing.</span></div>
<div class="line"><a id="l00800" name="l00800"></a><span class="lineno">  800</span>  X();</div>
<div class="line"><a id="l00801" name="l00801"></a><span class="lineno">  801</span> </div>
<div class="line"><a id="l00802" name="l00802"></a><span class="lineno">  802</span><span class="keyword">private</span>: <span class="comment">// Ditto.</span></div>
<div class="line"><a id="l00803" name="l00803"></a><span class="lineno">  803</span>  C m_data_member1;</div>
<div class="line"><a id="l00804" name="l00804"></a><span class="lineno">  804</span>  <span class="keywordtype">int</span> m_data_member2;</div>
<div class="line"><a id="l00805" name="l00805"></a><span class="lineno">  805</span>};</div>
<div class="line"><a id="l00806" name="l00806"></a><span class="lineno">  806</span> </div>
<div class="line"><a id="l00807" name="l00807"></a><span class="lineno">  807</span>X::X() : <span class="comment">// ATTN: initializers start on next line and indented to match the { body }.</span></div>
<div class="line"><a id="l00808" name="l00808"></a><span class="lineno">  808</span>  m_data_member1(rnd()),</div>
<div class="line"><a id="l00809" name="l00809"></a><span class="lineno">  809</span>  m_data_member2(0)</div>
<div class="line"><a id="l00810" name="l00810"></a><span class="lineno">  810</span>{</div>
<div class="line"><a id="l00811" name="l00811"></a><span class="lineno">  811</span>  <span class="keywordflow">switch</span> (<span class="comment">/* [...] */</span>) <span class="comment">// @todo This is the current convention, but it&#39;s kinda ugly TBH.  Consider adding indentation.</span></div>
<div class="line"><a id="l00812" name="l00812"></a><span class="lineno">  812</span>  {</div>
<div class="line"><a id="l00813" name="l00813"></a><span class="lineno">  813</span>  <span class="keywordflow">case</span> 0: <span class="comment">// Label again starts on same column as preceding thing.</span></div>
<div class="line"><a id="l00814" name="l00814"></a><span class="lineno">  814</span>    do_something0();</div>
<div class="line"><a id="l00815" name="l00815"></a><span class="lineno">  815</span>    <span class="keywordflow">break</span>;</div>
<div class="line"><a id="l00816" name="l00816"></a><span class="lineno">  816</span>  <span class="keywordflow">case</span> 1:</div>
<div class="line"><a id="l00817" name="l00817"></a><span class="lineno">  817</span>  { <span class="comment">// If you have declarations, use a { block } to segregate it;</span></div>
<div class="line"><a id="l00818" name="l00818"></a><span class="lineno">  818</span>    <span class="keyword">auto</span> x = rnd();</div>
<div class="line"><a id="l00819" name="l00819"></a><span class="lineno">  819</span>    do_something1(x);</div>
<div class="line"><a id="l00820" name="l00820"></a><span class="lineno">  820</span>    <span class="keywordflow">break</span>;</div>
<div class="line"><a id="l00821" name="l00821"></a><span class="lineno">  821</span>  }</div>
<div class="line"><a id="l00822" name="l00822"></a><span class="lineno">  822</span>  <span class="keywordflow">default</span>:</div>
<div class="line"><a id="l00823" name="l00823"></a><span class="lineno">  823</span>    <span class="keywordflow">goto</span> get_out;</div>
<div class="line"><a id="l00824" name="l00824"></a><span class="lineno">  824</span>  }</div>
<div class="line"><a id="l00825" name="l00825"></a><span class="lineno">  825</span> </div>
<div class="line"><a id="l00826" name="l00826"></a><span class="lineno">  826</span>  <span class="comment">// Alternative `switch` formatting, when all case bodies are single-statement, short returns:</span></div>
<div class="line"><a id="l00827" name="l00827"></a><span class="lineno">  827</span>  <span class="keywordflow">switch</span> (op_result())</div>
<div class="line"><a id="l00828" name="l00828"></a><span class="lineno">  828</span>  {</div>
<div class="line"><a id="l00829" name="l00829"></a><span class="lineno">  829</span>    <span class="keywordflow">case</span> Xfer_op_result::S_FULLY_XFERRED: <span class="keywordflow">return</span> <span class="stringliteral">&quot;FULLY_XFERRED&quot;</span>;</div>
<div class="line"><a id="l00830" name="l00830"></a><span class="lineno">  830</span>    <span class="keywordflow">case</span> Xfer_op_result::S_PARTIALLY_XFERRED: <span class="keywordflow">return</span> <span class="stringliteral">&quot;PARTIALLY_XFERRED&quot;</span>;</div>
<div class="line"><a id="l00831" name="l00831"></a><span class="lineno">  831</span>    <span class="keywordflow">case</span> Xfer_op_result::S_ERROR: <span class="keywordflow">return</span> <span class="stringliteral">&quot;ERROR&quot;</span>;</div>
<div class="line"><a id="l00832" name="l00832"></a><span class="lineno">  832</span>    <span class="keywordflow">default</span>: assert(<span class="keyword">false</span>);</div>
<div class="line"><a id="l00833" name="l00833"></a><span class="lineno">  833</span>  }</div>
<div class="line"><a id="l00834" name="l00834"></a><span class="lineno">  834</span> </div>
<div class="line"><a id="l00835" name="l00835"></a><span class="lineno">  835</span>get_out: <span class="comment">// A rare actual label.</span></div>
<div class="line"><a id="l00836" name="l00836"></a><span class="lineno">  836</span>} <span class="comment">// X::X()</span></div>
<div class="line"><a id="l00837" name="l00837"></a><span class="lineno">  837</span> </div>
<div class="line"><a id="l00838" name="l00838"></a><span class="lineno">  838</span><span class="comment">// -- STYLE GUIDE: Misc/loose ends --</span></div>
<div class="line"><a id="l00839" name="l00839"></a><span class="lineno">  839</span> </div>
<div class="line"><a id="l00840" name="l00840"></a><span class="lineno">  840</span><span class="preprocessor">#if 0 </span><span class="comment">// Do not do file-scope `using`.  [Rationale: It&#39;s criminal in .hpp; arguably obnoxious in long `.cpp`s.]</span></div>
<div class="line"><a id="l00841" name="l00841"></a><span class="lineno">  841</span><span class="keyword">using namespace </span>std; <span class="comment">// Just, no.</span></div>
<div class="line"><a id="l00842" name="l00842"></a><span class="lineno">  842</span><span class="keyword">using </span>std::string; <span class="comment">// More defensible, in .cpp, but we still don&#39;t do it.</span></div>
<div class="line"><a id="l00843" name="l00843"></a><span class="lineno">  843</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00844" name="l00844"></a><span class="lineno">  844</span> </div>
<div class="line"><a id="l00845" name="l00845"></a><span class="lineno">  845</span><span class="comment">// However, `using` (not `using namespace`) is ubiquitous at function scope.</span></div>
<div class="line"><a id="l00846" name="l00846"></a><span class="lineno">  846</span><span class="keywordtype">void</span> Cool_class::some_method()</div>
<div class="line"><a id="l00847" name="l00847"></a><span class="lineno">  847</span>{</div>
<div class="line"><a id="l00848" name="l00848"></a><span class="lineno">  848</span><span class="preprocessor">#if 0</span></div>
<div class="line"><a id="l00849" name="l00849"></a><span class="lineno">  849</span>  <span class="keyword">using namespace </span>std; <span class="comment">// Still, just, no.</span></div>
<div class="line"><a id="l00850" name="l00850"></a><span class="lineno">  850</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l00851" name="l00851"></a><span class="lineno">  851</span>  <span class="comment">/* It is allowed and *strongly encouraged* [but optional] to avoid all/most namespace `qualifiers::`</span></div>
<div class="line"><a id="l00852" name="l00852"></a><span class="lineno">  852</span><span class="comment">   * by pre-qualifying them via `using` and namespace aliases.</span></div>
<div class="line"><a id="l00853" name="l00853"></a><span class="lineno">  853</span><span class="comment">   *   - Always at the top of function.  Almost never in a lower scope.</span></div>
<div class="line"><a id="l00854" name="l00854"></a><span class="lineno">  854</span><span class="comment">   *   - Types and functions can be thus `using`ed.</span></div>
<div class="line"><a id="l00855" name="l00855"></a><span class="lineno">  855</span><span class="comment">   *   - Namespace aliases can go here too. */</span></div>
<div class="line"><a id="l00856" name="l00856"></a><span class="lineno">  856</span>  <span class="keyword">namespace </span>util = flow::log::util;</div>
<div class="line"><a id="l00857" name="l00857"></a><span class="lineno">  857</span>  <span class="keyword">using </span>std::string;</div>
<div class="line"><a id="l00858" name="l00858"></a><span class="lineno">  858</span>  <span class="keyword">using </span>util::cool_util_method;</div>
<div class="line"><a id="l00859" name="l00859"></a><span class="lineno">  859</span> </div>
<div class="line"><a id="l00860" name="l00860"></a><span class="lineno">  860</span>  <span class="comment">// 2 things are pre-qualified above; 1 thing is explicitly qualified.  The latter is usually avoided but is OK.</span></div>
<div class="line"><a id="l00861" name="l00861"></a><span class="lineno">  861</span>  <span class="keywordtype">string</span> x = cool_util_method() + util::some_free_function();</div>
<div class="line"><a id="l00862" name="l00862"></a><span class="lineno">  862</span>}</div>
<div class="line"><a id="l00863" name="l00863"></a><span class="lineno">  863</span> </div>
<div class="line"><a id="l00864" name="l00864"></a><span class="lineno">  864</span><span class="comment">// A bunch of subtleties when using complicated C++11 initializers, so just kinda follow some examples:</span></div>
<div class="line"><a id="l00865" name="l00865"></a><span class="lineno">  865</span><span class="keyword">const</span> boost::unordered_map&lt;Event_set::Event_type, Event_set::Func_ptr&gt;</div>
<div class="line"><a id="l00866" name="l00866"></a><span class="lineno">  866</span>        <span class="comment">// @todo It&#39;s a bit ambiguous what the indentation &quot;anchor&quot; column should be here....</span></div>
<div class="line"><a id="l00867" name="l00867"></a><span class="lineno">  867</span>        Event_set::S_EV_TYPE_TO_IS_ACTIVE_NODE_MTD</div>
<div class="line"><a id="l00868" name="l00868"></a><span class="lineno">  868</span>          <span class="comment">// Use judgment to either have {} innards indented on separate line(s) or in-line.  Examples of both:</span></div>
<div class="line"><a id="l00869" name="l00869"></a><span class="lineno">  869</span>          ({</div>
<div class="line"><a id="l00870" name="l00870"></a><span class="lineno">  870</span>             { Event_set::Event_type::S_PEER_SOCKET_READABLE, &amp;Node::sock_is_readable },</div>
<div class="line"><a id="l00871" name="l00871"></a><span class="lineno">  871</span>             <span class="comment">// ^-- Spaces around `contents` in `{ contents }`, when it&#39;s all on one line. --v</span></div>
<div class="line"><a id="l00872" name="l00872"></a><span class="lineno">  872</span>             { Event_set::Event_type::S_PEER_SOCKET_WRITABLE, &amp;Node::sock_is_writable },</div>
<div class="line"><a id="l00873" name="l00873"></a><span class="lineno">  873</span>             { Event_set::Event_type::S_SERVER_SOCKET_ACCEPTABLE, &amp;Node::serv_is_acceptable }</div>
<div class="line"><a id="l00874" name="l00874"></a><span class="lineno">  874</span>           });</div>
<div class="line"><a id="l00875" name="l00875"></a><span class="lineno">  875</span> </div>
<div class="line"><a id="l00876" name="l00876"></a><span class="lineno">  876</span><span class="comment">// Misc. convention:</span></div>
<div class="line"><a id="l00877" name="l00877"></a><span class="lineno">  877</span>T* x = <span class="keyword">nullptr</span>; <span class="comment">// This is OK, but Flow was written before nullptr was available; we just use the following:</span></div>
<div class="line"><a id="l00878" name="l00878"></a><span class="lineno">  878</span>T* x = 0; <span class="comment">// This is the Flow convention.  Note, no `NULL`!  NULL is C stuff, no need.</span></div>
<div class="line"><a id="l00879" name="l00879"></a><span class="lineno">  879</span> </div>
<div class="line"><a id="l00880" name="l00880"></a><span class="lineno">  880</span><span class="comment">// -- STYLE GUIDE: Header files and forwarding; _fwd.hpp pattern --</span></div>
<div class="line"><a id="l00881" name="l00881"></a><span class="lineno">  881</span> </div>
<div class="line"><a id="l00882" name="l00882"></a><span class="lineno">  882</span><span class="comment">/* Flow now follows the forwarding-header pattern observed in various Boost libraries, although I (ygoldfel) have not</span></div>
<div class="line"><a id="l00883" name="l00883"></a><span class="lineno">  883</span><span class="comment"> * seen this pattern formalized anywhere and first arrived at it in a certain other (currently larger) project which</span></div>
<div class="line"><a id="l00884" name="l00884"></a><span class="lineno">  884</span><span class="comment"> * depends on Flow.  I then back-applied this pattern to Flow itself.  While the presented convention looks laborious,</span></div>
<div class="line"><a id="l00885" name="l00885"></a><span class="lineno">  885</span><span class="comment"> * we assure you over time it will save time and pain.  It will help compile times and prevent circular-dependency</span></div>
<div class="line"><a id="l00886" name="l00886"></a><span class="lineno">  886</span><span class="comment"> * awfulness that would otherwise plague larger APIs.</span></div>
<div class="line"><a id="l00887" name="l00887"></a><span class="lineno">  887</span><span class="comment"> *</span></div>
<div class="line"><a id="l00888" name="l00888"></a><span class="lineno">  888</span><span class="comment"> * Note this convention applies not merely to the API exported to the user; it applies, also, to internal impl</span></div>
<div class="line"><a id="l00889" name="l00889"></a><span class="lineno">  889</span><span class="comment"> * code as it goes about its internal business (typically residing in detail/ sub-dirs).</span></div>
<div class="line"><a id="l00890" name="l00890"></a><span class="lineno">  890</span><span class="comment"> *</span></div>
<div class="line"><a id="l00891" name="l00891"></a><span class="lineno">  891</span><span class="comment"> * First the basic rules.  Consider any declared symbol at the file level (i.e., direct</span></div>
<div class="line"><a id="l00892" name="l00892"></a><span class="lineno">  892</span><span class="comment"> * member of a `namespace` -- not a data member): aggregate type (`struct`, `class`, `union`) or template thereof;</span></div>
<div class="line"><a id="l00893" name="l00893"></a><span class="lineno">  893</span><span class="comment"> * `enum` or `enum class` (note: elsewhere we recommend avoiding the former) or template thereof; type alias</span></div>
<div class="line"><a id="l00894" name="l00894"></a><span class="lineno">  894</span><span class="comment"> * (`typedef` or `using`, though note: elsewhere we recommend avoiding the former); variable or constant</span></div>
<div class="line"><a id="l00895" name="l00895"></a><span class="lineno">  895</span><span class="comment"> * (non-`constexpr`); free function including `operator`s.  (We exclude macros and `constexpr` &quot;variables&quot; for</span></div>
<div class="line"><a id="l00896" name="l00896"></a><span class="lineno">  896</span><span class="comment"> * now; but see discussion below in separate section.)  Note we are speaking only of symbols exported beyond a</span></div>
<div class="line"><a id="l00897" name="l00897"></a><span class="lineno">  897</span><span class="comment"> * given translation unit; items local to a translation unit (anon-namespace or `static` items in a .cpp file, etc.)</span></div>
<div class="line"><a id="l00898" name="l00898"></a><span class="lineno">  898</span><span class="comment"> * are not relevant here.</span></div>
<div class="line"><a id="l00899" name="l00899"></a><span class="lineno">  899</span><span class="comment"> *</span></div>
<div class="line"><a id="l00900" name="l00900"></a><span class="lineno">  900</span><span class="comment"> *   - Aggregate types and templates thereof:</span></div>
<div class="line"><a id="l00901" name="l00901"></a><span class="lineno">  901</span><span class="comment"> *     - It must be forward-declared (e.g., `class X;`, `template&lt;typename T&gt; struct Y;`) exactly once.</span></div>
<div class="line"><a id="l00902" name="l00902"></a><span class="lineno">  902</span><span class="comment"> *     - It must be separately defined (meaning with its body provided), in compatible fashion, exactly once.</span></div>
<div class="line"><a id="l00903" name="l00903"></a><span class="lineno">  903</span><span class="comment"> *       - As shown elsewhere, this definition must be fully Doxygen-documented, including a leading doc header.</span></div>
<div class="line"><a id="l00904" name="l00904"></a><span class="lineno">  904</span><span class="comment"> *   - Enumerations and templates thereof:</span></div>
<div class="line"><a id="l00905" name="l00905"></a><span class="lineno">  905</span><span class="comment"> *     - It must be declared/defined exactly once, together with its full Doxygen docs (including leading</span></div>
<div class="line"><a id="l00906" name="l00906"></a><span class="lineno">  906</span><span class="comment"> *       doc header).  Do not forward-declare.  (Rationale omitted: But trust us; trying to fwd-declare it is</span></div>
<div class="line"><a id="l00907" name="l00907"></a><span class="lineno">  907</span><span class="comment"> *       more trouble than it is worth; and avoiding it generally well with other nearby conventions.)</span></div>
<div class="line"><a id="l00908" name="l00908"></a><span class="lineno">  908</span><span class="comment"> *   - Type aliases:</span></div>
<div class="line"><a id="l00909" name="l00909"></a><span class="lineno">  909</span><span class="comment"> *     - It must be declared/defined exactly once (as required by C++), together with its Doxygen doc header.</span></div>
<div class="line"><a id="l00910" name="l00910"></a><span class="lineno">  910</span><span class="comment"> *   - Varibles and constants (non-`constexpr`):</span></div>
<div class="line"><a id="l00911" name="l00911"></a><span class="lineno">  911</span><span class="comment"> *     - It must be forward-declared exactly once with `extern` keyword: `extern T var;`, `extern const T CONSTANT;`,</span></div>
<div class="line"><a id="l00912" name="l00912"></a><span class="lineno">  912</span><span class="comment"> *       together with its doc header.</span></div>
<div class="line"><a id="l00913" name="l00913"></a><span class="lineno">  913</span><span class="comment"> *     - It must be separately defined (initialized) exactly once: `T var; // Possibly initialized also.`,</span></div>
<div class="line"><a id="l00914" name="l00914"></a><span class="lineno">  914</span><span class="comment"> *       `const T CONSTANT = ...;`, `const T CONSTANT(...);`.</span></div>
<div class="line"><a id="l00915" name="l00915"></a><span class="lineno">  915</span><span class="comment"> *   - Free functions:</span></div>
<div class="line"><a id="l00916" name="l00916"></a><span class="lineno">  916</span><span class="comment"> *     - It must be forward-declared (a/k/a prototyped) exactly once, together with its Doxygen docs including</span></div>
<div class="line"><a id="l00917" name="l00917"></a><span class="lineno">  917</span><span class="comment"> *       doc header.</span></div>
<div class="line"><a id="l00918" name="l00918"></a><span class="lineno">  918</span><span class="comment"> *     - It must be separately defined (meaning with its body provided) exactly once in compatible fashion.</span></div>
<div class="line"><a id="l00919" name="l00919"></a><span class="lineno">  919</span><span class="comment"> *</span></div>
<div class="line"><a id="l00920" name="l00920"></a><span class="lineno">  920</span><span class="comment"> * For each type of symbol, there are (as you can see) either 1 forward-declaration and 1 definition, or just</span></div>
<div class="line"><a id="l00921" name="l00921"></a><span class="lineno">  921</span><span class="comment"> * 1 declaration/definition.  You already will know from elsewhere in this doc (and general C++</span></div>
<div class="line"><a id="l00922" name="l00922"></a><span class="lineno">  922</span><span class="comment"> * knowledge) where to put most of these.  Briefly:</span></div>
<div class="line"><a id="l00923" name="l00923"></a><span class="lineno">  923</span><span class="comment"> *   - aggregate type definition/body goes in some header .hpp;</span></div>
<div class="line"><a id="l00924" name="l00924"></a><span class="lineno">  924</span><span class="comment"> *     - (but what about fwd declaration?);</span></div>
<div class="line"><a id="l00925" name="l00925"></a><span class="lineno">  925</span><span class="comment"> *   - same for enumeration definition/body;</span></div>
<div class="line"><a id="l00926" name="l00926"></a><span class="lineno">  926</span><span class="comment"> *   - same for type alias definition;</span></div>
<div class="line"><a id="l00927" name="l00927"></a><span class="lineno">  927</span><span class="comment"> *   - variable/constant `extern` declaration goes in some header .hpp; initialization in some .cpp;</span></div>
<div class="line"><a id="l00928" name="l00928"></a><span class="lineno">  928</span><span class="comment"> *   - free function prototype (fwd declaration) goes in some header .hpp;</span></div>
<div class="line"><a id="l00929" name="l00929"></a><span class="lineno">  929</span><span class="comment"> *     - free function definition/body goes in .cpp except for templates, `constexpr`s (functions), and</span></div>
<div class="line"><a id="l00930" name="l00930"></a><span class="lineno">  930</span><span class="comment"> *       `inline`s (which we elsewhere discourage in favor of LTO) which go in .hpp.</span></div>
<div class="line"><a id="l00931" name="l00931"></a><span class="lineno">  931</span><span class="comment"> *</span></div>
<div class="line"><a id="l00932" name="l00932"></a><span class="lineno">  932</span><span class="comment"> * Without the _fwd.hpp pattern, the more detailed conventions are as follows:</span></div>
<div class="line"><a id="l00933" name="l00933"></a><span class="lineno">  933</span><span class="comment"> *   - When something goes into an .hpp, put it in whatever .hpp file seems right.</span></div>
<div class="line"><a id="l00934" name="l00934"></a><span class="lineno">  934</span><span class="comment"> *   - If something requires a declaration and a *separate* definition, and the above says that both belong in</span></div>
<div class="line"><a id="l00935" name="l00935"></a><span class="lineno">  935</span><span class="comment"> *     .hpp, then just put them both into the same .hpp (declaration up-top; definition down below in impl area).</span></div>
<div class="line"><a id="l00936" name="l00936"></a><span class="lineno">  936</span><span class="comment"> *     The Doxygen doc header should be on the declaration, not the definition, so the user sees it first.</span></div>
<div class="line"><a id="l00937" name="l00937"></a><span class="lineno">  937</span><span class="comment"> *     - And furthermore fwd declarations of compound types are simply not specified... throw them in when</span></div>
<div class="line"><a id="l00938" name="l00938"></a><span class="lineno">  938</span><span class="comment"> *       circular definitions arise, but generally, whatever; just wing it.  However naturally the Doxygen docs</span></div>
<div class="line"><a id="l00939" name="l00939"></a><span class="lineno">  939</span><span class="comment"> *       shall be on the class/struct/etc. body itself and not any fwd-declaration of it.</span></div>
<div class="line"><a id="l00940" name="l00940"></a><span class="lineno">  940</span><span class="comment"> *</span></div>
<div class="line"><a id="l00941" name="l00941"></a><span class="lineno">  941</span><span class="comment"> * However -- in this pattern that is *not* correct (at least not usually).  Rather:</span></div>
<div class="line"><a id="l00942" name="l00942"></a><span class="lineno">  942</span><span class="comment"> *</span></div>
<div class="line"><a id="l00943" name="l00943"></a><span class="lineno">  943</span><span class="comment"> * **Key rule**: The forward-declaration, or only declaration+definition, shall usually be placed in a</span></div>
<div class="line"><a id="l00944" name="l00944"></a><span class="lineno">  944</span><span class="comment"> * *forward-header* file.  A forward-header shall always be named with form X_fwd.hpp.  This is not an *absolute*</span></div>
<div class="line"><a id="l00945" name="l00945"></a><span class="lineno">  945</span><span class="comment"> * rule, and exceptions to it are not all criminal; but they should be rare.  The more exceptions there are, the more</span></div>
<div class="line"><a id="l00946" name="l00946"></a><span class="lineno">  946</span><span class="comment"> * pain is likely to occur down the line.  We talk about good exception cases below.  For now let&#39;s forge on:</span></div>
<div class="line"><a id="l00947" name="l00947"></a><span class="lineno">  947</span><span class="comment"> *</span></div>
<div class="line"><a id="l00948" name="l00948"></a><span class="lineno">  948</span><span class="comment"> * That rule, in and of itself, is pretty simple.  Got a thing that must be declared/defined or forward-declared?</span></div>
<div class="line"><a id="l00949" name="l00949"></a><span class="lineno">  949</span><span class="comment"> * Put it in a _fwd.hpp.  If there&#39;s only one definition/declaration, then that&#39;s that.  If there&#39;s also a 2nd</span></div>
<div class="line"><a id="l00950" name="l00950"></a><span class="lineno">  950</span><span class="comment"> * definition/declaration (aggregate types/templates thereof; variables/constants; free functions/templates) then:</span></div>
<div class="line"><a id="l00951" name="l00951"></a><span class="lineno">  951</span><span class="comment"> *   - Any code requiring use of a given symbol can include the relevant _fwd.hpp when only a forward-declaration</span></div>
<div class="line"><a id="l00952" name="l00952"></a><span class="lineno">  952</span><span class="comment"> *     is required; e.g., if only referring to forward-declared type `T` by pointer or reference.</span></div>
<div class="line"><a id="l00953" name="l00953"></a><span class="lineno">  953</span><span class="comment"> *   - If it is insufficient (e.g., when `sizeof T` must be known to compiler), the code can include the non-_fwd.hpp</span></div>
<div class="line"><a id="l00954" name="l00954"></a><span class="lineno">  954</span><span class="comment"> *     header.</span></div>
<div class="line"><a id="l00955" name="l00955"></a><span class="lineno">  955</span><span class="comment"> *</span></div>
<div class="line"><a id="l00956" name="l00956"></a><span class="lineno">  956</span><span class="comment"> * This allows for (1) shorter build times; and (arguably more importantly) (2) the methodical pre-disentangling of</span></div>
<div class="line"><a id="l00957" name="l00957"></a><span class="lineno">  957</span><span class="comment"> * hairy circular-reference nightmares due to C++&#39;s single-pass compilation model.</span></div>
<div class="line"><a id="l00958" name="l00958"></a><span class="lineno">  958</span><span class="comment"> *</span></div>
<div class="line"><a id="l00959" name="l00959"></a><span class="lineno">  959</span><span class="comment"> * The convention gets somewhat annoying when it comes to the details of *which* _fwd.hpp to place the</span></div>
<div class="line"><a id="l00960" name="l00960"></a><span class="lineno">  960</span><span class="comment"> * declaration.  We note that different libraries do different things and not very consistently at that.  We give</span></div>
<div class="line"><a id="l00961" name="l00961"></a><span class="lineno">  961</span><span class="comment"> * it our best shot to nail it down and remove ambiguity for Flow.  Let&#39;s go: The _fwd.hpp files by convention are:</span></div>
<div class="line"><a id="l00962" name="l00962"></a><span class="lineno">  962</span><span class="comment"> *   - In top-level module/namespace flow::X, flow/X/X_fwd.hpp, a/k/a/ *top-level forward-header*.  Essentially this one</span></div>
<div class="line"><a id="l00963" name="l00963"></a><span class="lineno">  963</span><span class="comment"> *     always exists, assuming flow::X exports any symbol.</span></div>
<div class="line"><a id="l00964" name="l00964"></a><span class="lineno">  964</span><span class="comment"> *     - In some cases a top-level module may contain a sizable sub-module, in a sub-namespace; so namespace</span></div>
<div class="line"><a id="l00965" name="l00965"></a><span class="lineno">  965</span><span class="comment"> *       flow::X::...::Y.  Then there is potentially (not necessarily) flow/X/.../Y/Y_fwd.hpp, a/k/a</span></div>
<div class="line"><a id="l00966" name="l00966"></a><span class="lineno">  966</span><span class="comment"> *       *sub-level forward header*.</span></div>
<div class="line"><a id="l00967" name="l00967"></a><span class="lineno">  967</span><span class="comment"> *   - In a given detail/ sub-directory (direct or otherwise) of flow/X, so flow/X/.../Y/detail, there is potentially</span></div>
<div class="line"><a id="l00968" name="l00968"></a><span class="lineno">  968</span><span class="comment"> *     (not necessarily) flow/X/.../Y/detail/Y_fwd.hpp.  (Note: not detail_fwd.hpp or forward.hpp or ....)</span></div>
<div class="line"><a id="l00969" name="l00969"></a><span class="lineno">  969</span><span class="comment"> *     This is known as *detail-level forward-header*.</span></div>
<div class="line"><a id="l00970" name="l00970"></a><span class="lineno">  970</span><span class="comment"> *     - If the detail/ aspect of some module is particularly complex, there could be more sub-dirs under detail/;</span></div>
<div class="line"><a id="l00971" name="l00971"></a><span class="lineno">  971</span><span class="comment"> *       technically it may be desirable to have a lower-level Y/detail/A/.../B/B_fwd.hpp.  Hopefully you can reason</span></div>
<div class="line"><a id="l00972" name="l00972"></a><span class="lineno">  972</span><span class="comment"> *       out what to do on your own based on the below discussion, but we won&#39;t formally spend time getting into it.</span></div>
<div class="line"><a id="l00973" name="l00973"></a><span class="lineno">  973</span><span class="comment"> *       Use common sense/analogy thinking.</span></div>
<div class="line"><a id="l00974" name="l00974"></a><span class="lineno">  974</span><span class="comment"> *   - At any dir level, for a given C.hpp focused on central aggregate type (or aggregate type template, or namespace,</span></div>
<div class="line"><a id="l00975" name="l00975"></a><span class="lineno">  975</span><span class="comment"> *     or compact feature or ...) named ~C, there is potentially (not necessarily) C_fwd.hpp in the same dir.</span></div>
<div class="line"><a id="l00976" name="l00976"></a><span class="lineno">  976</span><span class="comment"> *     This is known as *header-specific forward-header*.</span></div>
<div class="line"><a id="l00977" name="l00977"></a><span class="lineno">  977</span><span class="comment"> *</span></div>
<div class="line"><a id="l00978" name="l00978"></a><span class="lineno">  978</span><span class="comment"> * First decide which of the ~3 locations your declaration belongs in; then create that _fwd.hpp if needed; and</span></div>
<div class="line"><a id="l00979" name="l00979"></a><span class="lineno">  979</span><span class="comment"> * then put the declaration there in the appropriate section.  So which one should it be?  Answer: it shall be either</span></div>
<div class="line"><a id="l00980" name="l00980"></a><span class="lineno">  980</span><span class="comment"> *   - in header-specific forward-header C_fwd.hpp; or</span></div>
<div class="line"><a id="l00981" name="l00981"></a><span class="lineno">  981</span><span class="comment"> *   - in a top-level or sub-level forward header flow/X/X_fwd.hpp or flow/X/.../Y/Y_fwd.hpp; or</span></div>
<div class="line"><a id="l00982" name="l00982"></a><span class="lineno">  982</span><span class="comment"> *   - in detail-level forward-header detail/Y_fwd.hpp (or possibly an even deeper-down one, but as noted we won&#39;t</span></div>
<div class="line"><a id="l00983" name="l00983"></a><span class="lineno">  983</span><span class="comment"> *     get into this and leave it as exercise to reader).</span></div>
<div class="line"><a id="l00984" name="l00984"></a><span class="lineno">  984</span><span class="comment"> *</span></div>
<div class="line"><a id="l00985" name="l00985"></a><span class="lineno">  985</span><span class="comment"> * Place a symbol info C_fwd.hpp if (1) it has to do with (e.g., free functions are common) with type/feature/whatever</span></div>
<div class="line"><a id="l00986" name="l00986"></a><span class="lineno">  986</span><span class="comment"> * (often class) C; and (2) the *total* set of symbols to-do with C (free functions at least usually identified with</span></div>
<div class="line"><a id="l00987" name="l00987"></a><span class="lineno">  987</span><span class="comment"> * Doxygen @relatesalso command) is subjectively *larger* than the following boring/vanilla set:</span></div>
<div class="line"><a id="l00988" name="l00988"></a><span class="lineno">  988</span><span class="comment"> * ostream&lt;&lt; operator, swap().  In other words if class/struct C comes with a sizable free-function/etc. API operating</span></div>
<div class="line"><a id="l00989" name="l00989"></a><span class="lineno">  989</span><span class="comment"> * on C-ish things, then stylistically they all belong in a segregated C_fwd.hpp that shall accompany C.hpp.</span></div>
<div class="line"><a id="l00990" name="l00990"></a><span class="lineno">  990</span><span class="comment"> * (So then C_fwd.hpp will contain free functions, class/etc. fwd-declarations, variable/constant `extern`</span></div>
<div class="line"><a id="l00991" name="l00991"></a><span class="lineno">  991</span><span class="comment"> * declarations, enum declarations, alias definitions; C.hpp will contain class/etc. bodies/definitions.)</span></div>
<div class="line"><a id="l00992" name="l00992"></a><span class="lineno">  992</span><span class="comment"> * Otherwise -- the typical case being a mere boring ostream&lt;&lt;C operator -- put it in a non-C-specific catch-all</span></div>
<div class="line"><a id="l00993" name="l00993"></a><span class="lineno">  993</span><span class="comment"> * _fwd.hpp shared among C and typically other entities.</span></div>
<div class="line"><a id="l00994" name="l00994"></a><span class="lineno">  994</span><span class="comment"> *</span></div>
<div class="line"><a id="l00995" name="l00995"></a><span class="lineno">  995</span><span class="comment"> * Supposing you chose a non-header-specific _fwd.hpp (which is typically indeed the easiest choice, except for</span></div>
<div class="line"><a id="l00996" name="l00996"></a><span class="lineno">  996</span><span class="comment"> * Cs with large free-function APIs), then you just need to pick which _fwd.hpp applies.  If your symbol</span></div>
<div class="line"><a id="l00997" name="l00997"></a><span class="lineno">  997</span><span class="comment"> * is under detail/, then use a detail-level forward-header; otherwise use a top-level or sub-level forward-header.</span></div>
<div class="line"><a id="l00998" name="l00998"></a><span class="lineno">  998</span><span class="comment"> *</span></div>
<div class="line"><a id="l00999" name="l00999"></a><span class="lineno">  999</span><span class="comment"> * In the latter case (which, again, is quite common), should it go into a top-level or sub-level forward-header?</span></div>
<div class="line"><a id="l01000" name="l01000"></a><span class="lineno"> 1000</span><span class="comment"> * Obviously if the symbol is directly in flow/X, then place it in the top-level X_fwd.hpp.  If however it&#39;s in</span></div>
<div class="line"><a id="l01001" name="l01001"></a><span class="lineno"> 1001</span><span class="comment"> * flow/X/.../Y, then it&#39;s a subjective decision.</span></div>
<div class="line"><a id="l01002" name="l01002"></a><span class="lineno"> 1002</span><span class="comment"> *   - Simplicity is best; so if it does not seem particularly offensive, just don&#39;t create sub-level forward-headers;</span></div>
<div class="line"><a id="l01003" name="l01003"></a><span class="lineno"> 1003</span><span class="comment"> *     just use the catch-all one at the top.</span></div>
<div class="line"><a id="l01004" name="l01004"></a><span class="lineno"> 1004</span><span class="comment"> *   - However, if truly a sub-module of flow/X is its own (large) animal that is intentionally segregated from</span></div>
<div class="line"><a id="l01005" name="l01005"></a><span class="lineno"> 1005</span><span class="comment"> *     the rest of flow/X, then you&#39;ll want to bite the bullet and create its own flow/X/.../Y/Y_fwd.hpp.</span></div>
<div class="line"><a id="l01006" name="l01006"></a><span class="lineno"> 1006</span><span class="comment"> *</span></div>
<div class="line"><a id="l01007" name="l01007"></a><span class="lineno"> 1007</span><span class="comment"> * Note on doc headers, in case it doesn&#39;t flow naturally from the above:</span></div>
<div class="line"><a id="l01008" name="l01008"></a><span class="lineno"> 1008</span><span class="comment"> *   - For the guys where there is only declaration/definition, obviously the doc headers shall be on that one.</span></div>
<div class="line"><a id="l01009" name="l01009"></a><span class="lineno"> 1009</span><span class="comment"> *   - For the guys where there is a declaration/prototype + separate definition/body:</span></div>
<div class="line"><a id="l01010" name="l01010"></a><span class="lineno"> 1010</span><span class="comment"> *     - Aggregate types: doc headers go above and throughout the definition/body (hence .hpp).</span></div>
<div class="line"><a id="l01011" name="l01011"></a><span class="lineno"> 1011</span><span class="comment"> *     - Constants/variables: doc header goes above the `extern` declaration (hence _fwd.hpp).</span></div>
<div class="line"><a id="l01012" name="l01012"></a><span class="lineno"> 1012</span><span class="comment"> *     - Free functions: doc header goes above the prototype (hence _fwd.hpp).</span></div>
<div class="line"><a id="l01013" name="l01013"></a><span class="lineno"> 1013</span><span class="comment"> *</span></div>
<div class="line"><a id="l01014" name="l01014"></a><span class="lineno"> 1014</span><span class="comment"> * I (ygoldfel) am sad at how many words I have written; and worry it might be hard to understand.  Nevertheless</span></div>
<div class="line"><a id="l01015" name="l01015"></a><span class="lineno"> 1015</span><span class="comment"> * I had to try to write it, if only to clarify my own thoughts on the matter for myself.  Hopefully it helps.</span></div>
<div class="line"><a id="l01016" name="l01016"></a><span class="lineno"> 1016</span><span class="comment"> *</span></div>
<div class="line"><a id="l01017" name="l01017"></a><span class="lineno"> 1017</span><span class="comment"> * That said, the most important thing is to be disciplined in placing the forward (or only) declaration in a _fwd.hpp</span></div>
<div class="line"><a id="l01018" name="l01018"></a><span class="lineno"> 1018</span><span class="comment"> * file.  It really does save pain as a project grows. */</span></div>
<div class="line"><a id="l01019" name="l01019"></a><span class="lineno"> 1019</span> </div>
<div class="line"><a id="l01020" name="l01020"></a><span class="lineno"> 1020</span><span class="comment">/* - Corollary: In more complex modules _fwd.hpp files will at times need to `include` other _fwd.hpp files, whether</span></div>
<div class="line"><a id="l01021" name="l01021"></a><span class="lineno"> 1021</span><span class="comment"> *   from the same module or others.  This should be straightforward to reason about; you&#39;ll see.  One corollary</span></div>
<div class="line"><a id="l01022" name="l01022"></a><span class="lineno"> 1022</span><span class="comment"> *   is that, if one follows the above rules, a _fwd.hpp will ~never contain struct/class/union or free-function bodies,</span></div>
<div class="line"><a id="l01023" name="l01023"></a><span class="lineno"> 1023</span><span class="comment"> *   only their forward-declarations and prototypes respectively.  A corollary of *that* is that if _fwd.hpp includes</span></div>
<div class="line"><a id="l01024" name="l01024"></a><span class="lineno"> 1024</span><span class="comment"> *   another (in-project) header, then it should ~always itself be _fwd.hpp.  Otherwise you&#39;ve broken the point of</span></div>
<div class="line"><a id="l01025" name="l01025"></a><span class="lineno"> 1025</span><span class="comment"> *   the outer _fwd.hpp&#39;s existence which is to *only* forward-declare things.  Otherwise compilation times may</span></div>
<div class="line"><a id="l01026" name="l01026"></a><span class="lineno"> 1026</span><span class="comment"> *   increase, and tricky circular issues may arise. */</span></div>
<div class="line"><a id="l01027" name="l01027"></a><span class="lineno"> 1027</span> </div>
<div class="line"><a id="l01028" name="l01028"></a><span class="lineno"> 1028</span><span class="comment">// -- STYLE GUIDE: Exceptions to _fwd.hpp pattern --</span></div>
<div class="line"><a id="l01029" name="l01029"></a><span class="lineno"> 1029</span> </div>
<div class="line"><a id="l01030" name="l01030"></a><span class="lineno"> 1030</span><span class="comment">/* As noted above: Above are not *absolute* rules, and exceptions to it are not all criminal; but they should be rare.</span></div>
<div class="line"><a id="l01031" name="l01031"></a><span class="lineno"> 1031</span><span class="comment"> * The more exceptions there are, the more pain is likely to occur down the line.</span></div>
<div class="line"><a id="l01032" name="l01032"></a><span class="lineno"> 1032</span><span class="comment"> *</span></div>
<div class="line"><a id="l01033" name="l01033"></a><span class="lineno"> 1033</span><span class="comment"> * Here are known reasonable exceptions as of this writing.</span></div>
<div class="line"><a id="l01034" name="l01034"></a><span class="lineno"> 1034</span><span class="comment"> *   - Usually a _fwd.hpp should not include a struct/class/union (or template thereof) body... but sometimes</span></div>
<div class="line"><a id="l01035" name="l01035"></a><span class="lineno"> 1035</span><span class="comment"> *     it is okay to do so.  Hand-wavily speaking this is the case when the type C is a *glorified alias* or</span></div>
<div class="line"><a id="l01036" name="l01036"></a><span class="lineno"> 1036</span><span class="comment"> *     *empty*.</span></div>
<div class="line"><a id="l01037" name="l01037"></a><span class="lineno"> 1037</span><span class="comment"> *     - Empty types, usually `struct C {}`, are used in the tag-parameter pattern among other things.</span></div>
<div class="line"><a id="l01038" name="l01038"></a><span class="lineno"> 1038</span><span class="comment"> *       They&#39;re fine to include directly in _fwd.hpp.  Omit the forward-declaration; declare directly in _fwd.hpp;</span></div>
<div class="line"><a id="l01039" name="l01039"></a><span class="lineno"> 1039</span><span class="comment"> *       include the doc header as you would normally in non-_fwd.hpp.</span></div>
<div class="line"><a id="l01040" name="l01040"></a><span class="lineno"> 1040</span><span class="comment"> *       - Similarly for types (for example flow::Container_traits) that lack any data but have only `static` constants</span></div>
<div class="line"><a id="l01041" name="l01041"></a><span class="lineno"> 1041</span><span class="comment"> *         and/or type aliases.</span></div>
<div class="line"><a id="l01042" name="l01042"></a><span class="lineno"> 1042</span><span class="comment"> *     - Consider a class/class template that non-virtually subclasses another class/class template but adds no</span></div>
<div class="line"><a id="l01043" name="l01043"></a><span class="lineno"> 1043</span><span class="comment"> *       data members outside of `static` constants -- so only a ctor/method API and/or static constants.  If this</span></div>
<div class="line"><a id="l01044" name="l01044"></a><span class="lineno"> 1044</span><span class="comment"> *       added API + constants is small enough -- e.g., adding convenience constructor(s)</span></div>
<div class="line"><a id="l01045" name="l01045"></a><span class="lineno"> 1045</span><span class="comment"> *       and/or a couple compatibility accessors -- then it can go into _fwd.hpp.  Omit the forward-declaration;</span></div>
<div class="line"><a id="l01046" name="l01046"></a><span class="lineno"> 1046</span><span class="comment"> *       declare directly in _fwd.hpp; place the doc header as you would normally in non-_fwd.hpp.  This class</span></div>
<div class="line"><a id="l01047" name="l01047"></a><span class="lineno"> 1047</span><span class="comment"> *       is &quot;almost&quot; an alias to its superclass.</span></div>
<div class="line"><a id="l01048" name="l01048"></a><span class="lineno"> 1048</span><span class="comment"> *       - If the class/class template C is too large to stylistically belong in a module-level _fwd.hpp, you might</span></div>
<div class="line"><a id="l01049" name="l01049"></a><span class="lineno"> 1049</span><span class="comment"> *         place it into its own C.hpp; but it is then okay to `include` in that _fwd.hpp.  If C is oft-used, this</span></div>
<div class="line"><a id="l01050" name="l01050"></a><span class="lineno"> 1050</span><span class="comment"> *         might be convenient for the user.</span></div>
<div class="line"><a id="l01051" name="l01051"></a><span class="lineno"> 1051</span><span class="comment"> *       - (For example Flow defines flow::Function&lt;&gt; which subclasses std::function&lt;&gt; and adds some minor convenience</span></div>
<div class="line"><a id="l01052" name="l01052"></a><span class="lineno"> 1052</span><span class="comment"> *         APIs but no data.)</span></div>
<div class="line"><a id="l01053" name="l01053"></a><span class="lineno"> 1053</span><span class="comment"> *     - Similarly consider a struct or class that merely wraps a single item, for type safety and/or to provide</span></div>
<div class="line"><a id="l01054" name="l01054"></a><span class="lineno"> 1054</span><span class="comment"> *       a little wrapper API.  For example: a `struct Native_handle { int m_fd; }` with a few niceties like</span></div>
<div class="line"><a id="l01055" name="l01055"></a><span class="lineno"> 1055</span><span class="comment"> *       an ostream&lt;&lt; operator and perhaps a couple convenience methods.  It is ~always copied by value, like an int.</span></div>
<div class="line"><a id="l01056" name="l01056"></a><span class="lineno"> 1056</span><span class="comment"> *       So it&#39;s &quot;almost&quot; an alias to the int.  So it can go into _fwd.hpp.  Again: Omit the forward-declaration;</span></div>
<div class="line"><a id="l01057" name="l01057"></a><span class="lineno"> 1057</span><span class="comment"> *       declare directly in _fwd.hpp; include the doc header as you would normally in non-_fwd.hpp.</span></div>
<div class="line"><a id="l01058" name="l01058"></a><span class="lineno"> 1058</span><span class="comment"> *       - Again you might instead put it into its own X.hpp... but then `include &quot;.../X.hpp&quot;` in module-level</span></div>
<div class="line"><a id="l01059" name="l01059"></a><span class="lineno"> 1059</span><span class="comment"> *         _fwd.hpp.</span></div>
<div class="line"><a id="l01060" name="l01060"></a><span class="lineno"> 1060</span><span class="comment"> *   - Top-level flow/common.hpp is something of a special case: It lives outside of (above) any top-level module;</span></div>
<div class="line"><a id="l01061" name="l01061"></a><span class="lineno"> 1061</span><span class="comment"> *     and it *is* a forward-header... but not named that way.  Still, that is what it is.  Anyway... it&#39;s a special</span></div>
<div class="line"><a id="l01062" name="l01062"></a><span class="lineno"> 1062</span><span class="comment"> *     case, and as noted in that file things should be added to it *very* sparingly in any case.  What if</span></div>
<div class="line"><a id="l01063" name="l01063"></a><span class="lineno"> 1063</span><span class="comment"> *     we want something &quot;heavy&quot; (a class body, for example) in common.hpp?  Doesn&#39;t that break the convention of</span></div>
<div class="line"><a id="l01064" name="l01064"></a><span class="lineno"> 1064</span><span class="comment"> *     not doing that in forward-headers?  Answer: yes, it hypothetically would, so you shouldn&#39;t do it... but</span></div>
<div class="line"><a id="l01065" name="l01065"></a><span class="lineno"> 1065</span><span class="comment"> *     as noted common.hpp is intentionally *very* limited/small.  If something is that big then it should go into</span></div>
<div class="line"><a id="l01066" name="l01066"></a><span class="lineno"> 1066</span><span class="comment"> *     flow::util or some other module, not directly into namespace `flow` and thus common.hpp.</span></div>
<div class="line"><a id="l01067" name="l01067"></a><span class="lineno"> 1067</span><span class="comment"> *     - Incidentally it happens to feature the aforementioned flow::Function&lt;&gt;, essentially or &quot;almost&quot; an alias</span></div>
<div class="line"><a id="l01068" name="l01068"></a><span class="lineno"> 1068</span><span class="comment"> *       to std::function. */</span></div>
<div class="line"><a id="l01069" name="l01069"></a><span class="lineno"> 1069</span> </div>
<div class="line"><a id="l01070" name="l01070"></a><span class="lineno"> 1070</span><span class="comment">// -- STYLE GUIDE: _fwd.hpp pattern odds/ends: Macros, constexpr globals --</span></div>
<div class="line"><a id="l01071" name="l01071"></a><span class="lineno"> 1071</span> </div>
<div class="line"><a id="l01072" name="l01072"></a><span class="lineno"> 1072</span><span class="comment">/* Where does a (functional) macro go?  _fwd.hpp or not?  If the former then which one?  For now we leave the answer</span></div>
<div class="line"><a id="l01073" name="l01073"></a><span class="lineno"> 1073</span><span class="comment"> * mostly as an exercise to the reader.  We&#39;ll only say this:</span></div>
<div class="line"><a id="l01074" name="l01074"></a><span class="lineno"> 1074</span><span class="comment"> *   - Macros (as noted elsewhere) should be avoided whenever possible (e.g., flow::log uses them, as there&#39;s ~no</span></div>
<div class="line"><a id="l01075" name="l01075"></a><span class="lineno"> 1075</span><span class="comment"> *     way to avoid it given the perf needs involved).  If you do need to export a macro, then remember *what* a macro</span></div>
<div class="line"><a id="l01076" name="l01076"></a><span class="lineno"> 1076</span><span class="comment"> *     is: The #define itself does not &quot;do&quot; anything: something only executes when this guy is actually invoked in</span></div>
<div class="line"><a id="l01077" name="l01077"></a><span class="lineno"> 1077</span><span class="comment"> *     user code.  The #define does not affect compile times really, nor do circular dependencies really apply to it.</span></div>
<div class="line"><a id="l01078" name="l01078"></a><span class="lineno"> 1078</span><span class="comment"> *   - One rule of thumb might be:</span></div>
<div class="line"><a id="l01079" name="l01079"></a><span class="lineno"> 1079</span><span class="comment"> *     - Macro goes in _fwd.hpp if and only if *every* symbol it needs -- directly or indirectly -- can be and is</span></div>
<div class="line"><a id="l01080" name="l01080"></a><span class="lineno"> 1080</span><span class="comment"> *       (directly or indirectly) `include`d by the same _fwd.hpp (which means each lives in this or other _fwd.hpp),</span></div>
<div class="line"><a id="l01081" name="l01081"></a><span class="lineno"> 1081</span><span class="comment"> *       enough so to compile without additional `include`s by the user.</span></div>
<div class="line"><a id="l01082" name="l01082"></a><span class="lineno"> 1082</span><span class="comment"> *     - Otherwise it goes in non-_fwd.hpp (which must also, directly or indirectly, supply all necessarily</span></div>
<div class="line"><a id="l01083" name="l01083"></a><span class="lineno"> 1083</span><span class="comment"> *       symbols by `include`ing the proper headers to avoid compile or link error). /</span></div>
<div class="line"><a id="l01084" name="l01084"></a><span class="lineno"> 1084</span><span class="comment"></span> </div>
<div class="line"><a id="l01085" name="l01085"></a><span class="lineno"> 1085</span><span class="comment">/* What about a constexpr global (a constant)?  For now we skip this topic.  The current suggestion is to not use</span></div>
<div class="line"><a id="l01086" name="l01086"></a><span class="lineno"> 1086</span><span class="comment"> * such constexpr globals; `static constexpr` class/struct members should be sufficient, if indeed constexpr is</span></div>
<div class="line"><a id="l01087" name="l01087"></a><span class="lineno"> 1087</span><span class="comment"> * required.  If this changes we&#39;ll develop a convention in this spot.  It might rely on the C++17 `inline constexpr`</span></div>
<div class="line"><a id="l01088" name="l01088"></a><span class="lineno"> 1088</span><span class="comment"> * syntax perhaps.  TODO: Cross that bridge when we come to it. */</span></div>
<div class="line"><a id="l01089" name="l01089"></a><span class="lineno"> 1089</span> </div>
<div class="line"><a id="l01090" name="l01090"></a><span class="lineno"> 1090</span><span class="comment">// -- BEST PRACTICES --</span></div>
<div class="line"><a id="l01091" name="l01091"></a><span class="lineno"> 1091</span> </div>
<div class="line"><a id="l01092" name="l01092"></a><span class="lineno"> 1092</span><span class="comment">/* The rest of the doc lists various best practices, which we&#39;ve already explained are guidelines that subjectively</span></div>
<div class="line"><a id="l01093" name="l01093"></a><span class="lineno"> 1093</span><span class="comment"> * help readability, maintainability, and elegance.  To be clear:</span></div>
<div class="line"><a id="l01094" name="l01094"></a><span class="lineno"> 1094</span><span class="comment"> *   - These are no more or less mandatory than the cosmetic STYLE GUIDE rules above.  However, due to their subjective</span></div>
<div class="line"><a id="l01095" name="l01095"></a><span class="lineno"> 1095</span><span class="comment"> *     nature, their correctness is much more arguable; and (as a corollary to that) good reasons to bend or break</span></div>
<div class="line"><a id="l01096" name="l01096"></a><span class="lineno"> 1096</span><span class="comment"> *     a &quot;best practice&quot; tend to be much more frequent than for the cosmetic guidelines.</span></div>
<div class="line"><a id="l01097" name="l01097"></a><span class="lineno"> 1097</span><span class="comment"> *   - The cosmetic rules come close to being exhaustive, meaning you&#39;re free to do whatever you want, as long as</span></div>
<div class="line"><a id="l01098" name="l01098"></a><span class="lineno"> 1098</span><span class="comment"> *     you don&#39;t break the existing cosmetic conventions.  The BEST PRACTICES, however, are nowhere near exhaustive!</span></div>
<div class="line"><a id="l01099" name="l01099"></a><span class="lineno"> 1099</span><span class="comment"> *     Good style is something picked up over years, even decades.  Entire famous books are written about it</span></div>
<div class="line"><a id="l01100" name="l01100"></a><span class="lineno"> 1100</span><span class="comment"> *     (e.g., &quot;Effective C++&quot; by Meyer).  Some patterns are hard to even explain due to various details and caveats.</span></div>
<div class="line"><a id="l01101" name="l01101"></a><span class="lineno"> 1101</span><span class="comment"> *     - *Therefore*, the following isn&#39;t even a little exhaustive: more like a list of things that:</span></div>
<div class="line"><a id="l01102" name="l01102"></a><span class="lineno"> 1102</span><span class="comment"> *       - have come to mind; and</span></div>
<div class="line"><a id="l01103" name="l01103"></a><span class="lineno"> 1103</span><span class="comment"> *       - are fairly uncontroversial; and</span></div>
<div class="line"><a id="l01104" name="l01104"></a><span class="lineno"> 1104</span><span class="comment"> *       - can be described in a few paragraphs at most -- ideally only 1 -- including the [rationale] if needed; and</span></div>
<div class="line"><a id="l01105" name="l01105"></a><span class="lineno"> 1105</span><span class="comment"> *       - are sufficiently high-impact to deserve the real estate in this doc.</span></div>
<div class="line"><a id="l01106" name="l01106"></a><span class="lineno"> 1106</span><span class="comment"> *</span></div>
<div class="line"><a id="l01107" name="l01107"></a><span class="lineno"> 1107</span><span class="comment"> * Note: Add more of these, as they come up.  Anyone can add them but must pass code review, like regular code.</span></div>
<div class="line"><a id="l01108" name="l01108"></a><span class="lineno"> 1108</span><span class="comment"> * Like, one can&#39;t just decide for everyone that multiple inheritance isn&#39;t allowed -- without review.</span></div>
<div class="line"><a id="l01109" name="l01109"></a><span class="lineno"> 1109</span><span class="comment"> * Ideas that feel controversial should be kicked up to a wider team as well. */</span></div>
<div class="line"><a id="l01110" name="l01110"></a><span class="lineno"> 1110</span> </div>
<div class="line"><a id="l01111" name="l01111"></a><span class="lineno"> 1111</span><span class="comment">// -- BEST PRACTICES: Comments --</span></div>
<div class="line"><a id="l01112" name="l01112"></a><span class="lineno"> 1112</span> </div>
<div class="line"><a id="l01113" name="l01113"></a><span class="lineno"> 1113</span><span class="comment">/* - Explain anything *possibly* unclear to a solid-but-unfamiliar coder, via comments written in plain English. -</span></div>
<div class="line"><a id="l01114" name="l01114"></a><span class="lineno"> 1114</span><span class="comment"> *</span></div>
<div class="line"><a id="l01115" name="l01115"></a><span class="lineno"> 1115</span><span class="comment"> * If something could *possibly* be unclear to a solid coder *unfamiliar* with the code base or specific subject matter,</span></div>
<div class="line"><a id="l01116" name="l01116"></a><span class="lineno"> 1116</span><span class="comment"> * just explain it with a comment!  Use plain English, not cryptic scribblings, even if it&#39;s less pithy.</span></div>
<div class="line"><a id="l01117" name="l01117"></a><span class="lineno"> 1117</span><span class="comment"> *</span></div>
<div class="line"><a id="l01118" name="l01118"></a><span class="lineno"> 1118</span><span class="comment"> *   JUST.  EXPLAIN.  THINGS.  IN ENGLISH.  UNLESS ABSOLUTELY OBVIOUS.</span></div>
<div class="line"><a id="l01119" name="l01119"></a><span class="lineno"> 1119</span><span class="comment"> *</span></div>
<div class="line"><a id="l01120" name="l01120"></a><span class="lineno"> 1120</span><span class="comment"> * If you&#39;re unsure whether something is obvious or not, just assume not.  Worst-case, it&#39;ll be redundant.  So?</span></div>
<div class="line"><a id="l01121" name="l01121"></a><span class="lineno"> 1121</span><span class="comment"> * It&#39;s worth it.</span></div>
<div class="line"><a id="l01122" name="l01122"></a><span class="lineno"> 1122</span><span class="comment"> *</span></div>
<div class="line"><a id="l01123" name="l01123"></a><span class="lineno"> 1123</span><span class="comment"> * Whether it&#39;s laziness or the inexplicable feeling that long comments are just not &quot;cool,&quot; most coders are very</span></div>
<div class="line"><a id="l01124" name="l01124"></a><span class="lineno"> 1124</span><span class="comment"> * lacking in this area by default.  Let&#39;s not be that way. */</span></div>
<div class="line"><a id="l01125" name="l01125"></a><span class="lineno"> 1125</span> </div>
<div class="line"><a id="l01126" name="l01126"></a><span class="lineno"> 1126</span><span class="comment">/* - Doc header (comment) of *any* function *must* describe the black-box contract of the function. -</span></div>
<div class="line"><a id="l01127" name="l01127"></a><span class="lineno"> 1127</span><span class="comment"> *</span></div>
<div class="line"><a id="l01128" name="l01128"></a><span class="lineno"> 1128</span><span class="comment"> * It *must* describe fully how to *use* f() as black box, without</span></div>
<div class="line"><a id="l01129" name="l01129"></a><span class="lineno"> 1129</span><span class="comment"> * requiring one to look at its code (if that were even possible, which it often isn&#39;t).  This black-box description</span></div>
<div class="line"><a id="l01130" name="l01130"></a><span class="lineno"> 1130</span><span class="comment"> * must not include implementation details.  This is a/k/a the function&#39;s *contract*, and it is holy.</span></div>
<div class="line"><a id="l01131" name="l01131"></a><span class="lineno"> 1131</span><span class="comment"> *   - You may use the language of &quot;pre-conditions&quot; and &quot;post-conditions.&quot;  It&#39;s not mandatory but can be helpful for</span></div>
<div class="line"><a id="l01132" name="l01132"></a><span class="lineno"> 1132</span><span class="comment"> *     clarity for more complex `f()`s.</span></div>
<div class="line"><a id="l01133" name="l01133"></a><span class="lineno"> 1133</span><span class="comment"> *</span></div>
<div class="line"><a id="l01134" name="l01134"></a><span class="lineno"> 1134</span><span class="comment"> * The f() comment *may* discuss implementation details in additional, clearly marked 1+ paragraphs.</span></div>
<div class="line"><a id="l01135" name="l01135"></a><span class="lineno"> 1135</span><span class="comment"> *   - Typically implementation is best-discussed inside the { body }, so putting it in doc header is fairly rare.</span></div>
<div class="line"><a id="l01136" name="l01136"></a><span class="lineno"> 1136</span><span class="comment"> *     (*Sometimes* user&#39;s &quot;how to use&quot; insight is increased by knowing some key aspect of implementation.)</span></div>
<div class="line"><a id="l01137" name="l01137"></a><span class="lineno"> 1137</span><span class="comment"> *</span></div>
<div class="line"><a id="l01138" name="l01138"></a><span class="lineno"> 1138</span><span class="comment"> * This rule can be regularly bent in only 1 instance: A `private` (or conceptually equivalent, like `static` free)</span></div>
<div class="line"><a id="l01139" name="l01139"></a><span class="lineno"> 1139</span><span class="comment"> * f() can be documented in a more white-box fashion when a formal black-box contract would feel silly.  Basically,</span></div>
<div class="line"><a id="l01140" name="l01140"></a><span class="lineno"> 1140</span><span class="comment"> * little obscure helpers can bend the rule within reason.  At your discretion, say something like &quot;Helper of [...]&#39;</span></div>
<div class="line"><a id="l01141" name="l01141"></a><span class="lineno"> 1141</span><span class="comment"> * that [...does basically so-and-so...]; see its code for further info. &quot;  However, @param, @tparam, and @return must</span></div>
<div class="line"><a id="l01142" name="l01142"></a><span class="lineno"> 1142</span><span class="comment"> * all be formally commented even so.</span></div>
<div class="line"><a id="l01143" name="l01143"></a><span class="lineno"> 1143</span><span class="comment"> *</span></div>
<div class="line"><a id="l01144" name="l01144"></a><span class="lineno"> 1144</span><span class="comment"> * [Rationale: The benefits are:</span></div>
<div class="line"><a id="l01145" name="l01145"></a><span class="lineno"> 1145</span><span class="comment"> *   - The obvious: Reader/maintainer can quickly understand f() without looking inside f() {} (which might even be</span></div>
<div class="line"><a id="l01146" name="l01146"></a><span class="lineno"> 1146</span><span class="comment"> *     unavailable).</span></div>
<div class="line"><a id="l01147" name="l01147"></a><span class="lineno"> 1147</span><span class="comment"> *   - The subtle but important: It helps avoid spaghetti code!  Essentially, f() is an abstract component that</span></div>
<div class="line"><a id="l01148" name="l01148"></a><span class="lineno"> 1148</span><span class="comment"> *     performs a black-box task.  By forcing coder to explicitly describe it *as* a black box, it tends to discourage</span></div>
<div class="line"><a id="l01149" name="l01149"></a><span class="lineno"> 1149</span><span class="comment"> *     abstraction-breaking designs that require the caller to worry about the callee&#39;s innards.  It&#39;s</span></div>
<div class="line"><a id="l01150" name="l01150"></a><span class="lineno"> 1150</span><span class="comment"> *     a powerful anti-spaghetti technique in our long experience.] */</span></div>
<div class="line"><a id="l01151" name="l01151"></a><span class="lineno"> 1151</span> </div>
<div class="line"><a id="l01152" name="l01152"></a><span class="lineno"> 1152</span><span class="comment">/* - Every class (and other compound types) *must* have a user-guide-like doc header with a black-box contract. -</span></div>
<div class="line"><a id="l01153" name="l01153"></a><span class="lineno"> 1153</span><span class="comment"> *</span></div>
<div class="line"><a id="l01154" name="l01154"></a><span class="lineno"> 1154</span><span class="comment"> * In spirit it&#39;s similar to the guideline above re. function doc headers.  In practice the class doc header requires</span></div>
<div class="line"><a id="l01155" name="l01155"></a><span class="lineno"> 1155</span><span class="comment"> * more effort however.  Rule of thumb for what to include in a class/struct/etc. doc header (in order):</span></div>
<div class="line"><a id="l01156" name="l01156"></a><span class="lineno"> 1156</span><span class="comment"> *   - The first pre-period sentence (&quot;brief&quot; in Doxygen parlance): Describe what an object of this type represents</span></div>
<div class="line"><a id="l01157" name="l01157"></a><span class="lineno"> 1157</span><span class="comment"> *     and any major capabilities, within reason.</span></div>
<div class="line"><a id="l01158" name="l01158"></a><span class="lineno"> 1158</span><span class="comment"> *   - The following paragraph (or the rest of the 1st one) may expand on that, featuring the most essential black-box</span></div>
<div class="line"><a id="l01159" name="l01159"></a><span class="lineno"> 1159</span><span class="comment"> *     information.</span></div>
<div class="line"><a id="l01160" name="l01160"></a><span class="lineno"> 1160</span><span class="comment"> *   - Next, explain *how to use* the class/whatever (a/k/a an object&#39;s life cycle).  Like: First, you construct it with</span></div>
<div class="line"><a id="l01161" name="l01161"></a><span class="lineno"> 1161</span><span class="comment"> *     purpose/details X.  Then, you use so-and-so methods; then after that you may use these other methods.  Destroy</span></div>
<div class="line"><a id="l01162" name="l01162"></a><span class="lineno"> 1162</span><span class="comment"> *     the object when Y.  Spend multiple paragraphs if helpful for clarity.  Pithy is good but clear is better!</span></div>
<div class="line"><a id="l01163" name="l01163"></a><span class="lineno"> 1163</span><span class="comment"> *     - All the members (including functions) must be documented with doc headers; so no need to get into that except</span></div>
<div class="line"><a id="l01164" name="l01164"></a><span class="lineno"> 1164</span><span class="comment"> *       for clarity.  Worst-case, they&#39;ll go and look at the method/whatever, especially if you mention the thing</span></div>
<div class="line"><a id="l01165" name="l01165"></a><span class="lineno"> 1165</span><span class="comment"> *       as noteworthy.</span></div>
<div class="line"><a id="l01166" name="l01166"></a><span class="lineno"> 1166</span><span class="comment"> *   - (Optional, often not needed)  Discuss implementation strategy.  This must be clearly marked, same as with f()</span></div>
<div class="line"><a id="l01167" name="l01167"></a><span class="lineno"> 1167</span><span class="comment"> *     doc headers.  However, unlike with f(), it is often *better* to discuss implementation strategy in the doc</span></div>
<div class="line"><a id="l01168" name="l01168"></a><span class="lineno"> 1168</span><span class="comment"> *     header, as there&#39;s no good other place (unlike with functions, where f(){ } comments are a fine place for it).</span></div>
<div class="line"><a id="l01169" name="l01169"></a><span class="lineno"> 1169</span><span class="comment"> *     - If the class/struct/whatever is part of the public API, place `@internal` before this discussion, so that</span></div>
<div class="line"><a id="l01170" name="l01170"></a><span class="lineno"> 1170</span><span class="comment"> *       the public API generated docs omit these blatantly white-box (internal) explanations.</span></div>
<div class="line"><a id="l01171" name="l01171"></a><span class="lineno"> 1171</span><span class="comment"> *   - A list of any `@todo`s.  Black-box/feature to-dos typically go at the end of black-box write-up;</span></div>
<div class="line"><a id="l01172" name="l01172"></a><span class="lineno"> 1172</span><span class="comment"> *     Internal/white-box to-dos at the end of the optional implementation write-up.  Each @todo is like one of these:</span></div>
<div class="line"><a id="l01173" name="l01173"></a><span class="lineno"> 1173</span><span class="comment"> *     - @todo One pre-period sentence sufficiently describing a simple to-do.</span></div>
<div class="line"><a id="l01174" name="l01174"></a><span class="lineno"> 1174</span><span class="comment"> *     - @todo One pre-colon sentence summarizing the complex to-do: Then get into as much detail as desired within</span></div>
<div class="line"><a id="l01175" name="l01175"></a><span class="lineno"> 1175</span><span class="comment"> *       reason, to make the to-do easier to &quot;do&quot; for the person reading it much later.  Keep going and going but</span></div>
<div class="line"><a id="l01176" name="l01176"></a><span class="lineno"> 1176</span><span class="comment"> *       absolutely no more than one paragraph.  Indentation should be as seen here.</span></div>
<div class="line"><a id="l01177" name="l01177"></a><span class="lineno"> 1177</span><span class="comment"> *     - Note: Following 1 of those 2 formats will produce a nice-looking generated TO-DO page via Doxygen.</span></div>
<div class="line"><a id="l01178" name="l01178"></a><span class="lineno"> 1178</span><span class="comment"> *     - Note: `@todo`s on functions and other members are fine too.  Class/etc. doc headers are just a natural place</span></div>
<div class="line"><a id="l01179" name="l01179"></a><span class="lineno"> 1179</span><span class="comment"> *       for the bulk of them.</span></div>
<div class="line"><a id="l01180" name="l01180"></a><span class="lineno"> 1180</span><span class="comment"> *   - Similarly a list of any `@note` and/or `@see` paragraphs.  Indent them similarly to @param.  There&#39;s no</span></div>
<div class="line"><a id="l01181" name="l01181"></a><span class="lineno"> 1181</span><span class="comment"> *     special page generated by Doxygen for these, so this is purely for readability pleasantness and could instead</span></div>
<div class="line"><a id="l01182" name="l01182"></a><span class="lineno"> 1182</span><span class="comment"> *     be directly in regular doc header text.  Whatever seems clearest is fine.</span></div>
<div class="line"><a id="l01183" name="l01183"></a><span class="lineno"> 1183</span><span class="comment"> *</span></div>
<div class="line"><a id="l01184" name="l01184"></a><span class="lineno"> 1184</span><span class="comment"> * All but the first 1-2 bullet points can often be omitted for simple compound types such as data-store `struct`s.</span></div>
<div class="line"><a id="l01185" name="l01185"></a><span class="lineno"> 1185</span><span class="comment"> *</span></div>
<div class="line"><a id="l01186" name="l01186"></a><span class="lineno"> 1186</span><span class="comment"> * [Rationale: In our experience, few coders do this by default.  Class doc headers tend to be non-existent or very</span></div>
<div class="line"><a id="l01187" name="l01187"></a><span class="lineno"> 1187</span><span class="comment"> * lacking.  Yet also in our experience these tend to be the most useful comments and hence most painful when omitted.</span></div>
<div class="line"><a id="l01188" name="l01188"></a><span class="lineno"> 1188</span><span class="comment"> * Classes are central entities, so these comments (when good) tend to help the most in explaining how stuff works</span></div>
<div class="line"><a id="l01189" name="l01189"></a><span class="lineno"> 1189</span><span class="comment"> * at a high level (a/k/a the architecture).  If I don&#39;t broadly know what the class is *for*, I will tend to write</span></div>
<div class="line"><a id="l01190" name="l01190"></a><span class="lineno"> 1190</span><span class="comment"> * ad-hoc (spaghetti) code due to lacking this conceptual understanding and instead understanding it &quot;heuristically,&quot;</span></div>
<div class="line"><a id="l01191" name="l01191"></a><span class="lineno"> 1191</span><span class="comment"> * by observation of how it&#39;s already used.  And if those use sites aren&#39;t well commented... then....] */</span></div>
<div class="line"><a id="l01192" name="l01192"></a><span class="lineno"> 1192</span> </div>
<div class="line"><a id="l01193" name="l01193"></a><span class="lineno"> 1193</span><span class="comment">// - If something is already *clearly* expressed with code, don&#39;t add a redundant *in-line* comment saying it again. -</span></div>
<div class="line"><a id="l01194" name="l01194"></a><span class="lineno"> 1194</span><span class="preprocessor">#if 0 </span><span class="comment">// NO.  Not helpful.</span></div>
<div class="line"><a id="l01195" name="l01195"></a><span class="lineno"> 1195</span><span class="keywordflow">if</span> (mutex.locked()) <span class="comment">// Mutex being locked here means we are in trouble.</span></div>
<div class="line"><a id="l01196" name="l01196"></a><span class="lineno"> 1196</span>{</div>
<div class="line"><a id="l01197" name="l01197"></a><span class="lineno"> 1197</span>  throw_error();</div>
<div class="line"><a id="l01198" name="l01198"></a><span class="lineno"> 1198</span>}</div>
<div class="line"><a id="l01199" name="l01199"></a><span class="lineno"> 1199</span><span class="preprocessor">#endif</span></div>
<div class="line"><a id="l01200" name="l01200"></a><span class="lineno"> 1200</span> </div>
<div class="line"><a id="l01201" name="l01201"></a><span class="lineno"> 1201</span><span class="comment">// -- BEST PRACTICES: Inlining --</span></div>
<div class="line"><a id="l01202" name="l01202"></a><span class="lineno"> 1202</span> </div>
<div class="line"><a id="l01203" name="l01203"></a><span class="lineno"> 1203</span><span class="comment">/* - Do not use explicit or implicit inlining; let compiler/linker handle it. -</span></div>
<div class="line"><a id="l01204" name="l01204"></a><span class="lineno"> 1204</span><span class="comment"> *</span></div>
<div class="line"><a id="l01205" name="l01205"></a><span class="lineno"> 1205</span><span class="comment"> * This requires some discussion.  As you may well know, there are two ways to make a function or method inlined</span></div>
<div class="line"><a id="l01206" name="l01206"></a><span class="lineno"> 1206</span><span class="comment"> * in the generated code:</span></div>
<div class="line"><a id="l01207" name="l01207"></a><span class="lineno"> 1207</span><span class="comment"> *   - Declare the thing `inline` in X.hpp, then later in same X.hpp provide the { body }.</span></div>
<div class="line"><a id="l01208" name="l01208"></a><span class="lineno"> 1208</span><span class="comment"> *   - For class/struct methods only, place the { body } directly at the method&#39;s declaration inside the</span></div>
<div class="line"><a id="l01209" name="l01209"></a><span class="lineno"> 1209</span><span class="comment"> *     class/struct { body }.  (It&#39;s commonly used for accessors; also for example code snippets.)</span></div>
<div class="line"><a id="l01210" name="l01210"></a><span class="lineno"> 1210</span><span class="comment"> *</span></div>
<div class="line"><a id="l01211" name="l01211"></a><span class="lineno"> 1211</span><span class="comment"> * Either way, this will (in most cases, excluding recursion and such) force the compiler to inline the function.</span></div>
<div class="line"><a id="l01212" name="l01212"></a><span class="lineno"> 1212</span><span class="comment"> * The rule here is:</span></div>
<div class="line"><a id="l01213" name="l01213"></a><span class="lineno"> 1213</span><span class="comment"> *   - Simply don&#39;t do that ever.</span></div>
<div class="line"><a id="l01214" name="l01214"></a><span class="lineno"> 1214</span><span class="comment"> *   - Instead, we will use `gcc -O3` or equivalent, so that the compiler/linker will decide for us when things</span></div>
<div class="line"><a id="l01215" name="l01215"></a><span class="lineno"> 1215</span><span class="comment"> *     should be inlined.</span></div>
<div class="line"><a id="l01216" name="l01216"></a><span class="lineno"> 1216</span><span class="comment"> *</span></div>
<div class="line"><a id="l01217" name="l01217"></a><span class="lineno"> 1217</span><span class="comment"> * [Rationale: The positives are as follows.  Firstly, compilation is much faster in many situations: changing</span></div>
<div class="line"><a id="l01218" name="l01218"></a><span class="lineno"> 1218</span><span class="comment"> * { body } in X.cpp instead of in X.hpp means only X.cpp must be recompiled; otherwise potentially *everything*</span></div>
<div class="line"><a id="l01219" name="l01219"></a><span class="lineno"> 1219</span><span class="comment"> * must be recompiled.  This can speed up day-to-day work by a ton; much less waiting for compilation to complete.</span></div>
<div class="line"><a id="l01220" name="l01220"></a><span class="lineno"> 1220</span><span class="comment"> * Secondly, it&#39;s better stylistically: declarations go in headers; implementations go in .cpp; and this is always</span></div>
<div class="line"><a id="l01221" name="l01221"></a><span class="lineno"> 1221</span><span class="comment"> * consistent, except for templates where &quot;c&#39;est la vie.&quot;  Thirdly, it removes the onus from the developer in terms of</span></div>
<div class="line"><a id="l01222" name="l01222"></a><span class="lineno"> 1222</span><span class="comment"> * deciding what is worth inlining and what isn&#39;t; the compiler can deal with it.</span></div>
<div class="line"><a id="l01223" name="l01223"></a><span class="lineno"> 1223</span><span class="comment"> *</span></div>
<div class="line"><a id="l01224" name="l01224"></a><span class="lineno"> 1224</span><span class="comment"> * There *is* a significant negative however.  The compiler is great at auto-inlining things within a given</span></div>
<div class="line"><a id="l01225" name="l01225"></a><span class="lineno"> 1225</span><span class="comment"> * translation unit (.cpp-&gt;.o, basically).  However if X.cpp calls something inlined in Y.cpp, then X.cpp invoking</span></div>
<div class="line"><a id="l01226" name="l01226"></a><span class="lineno"> 1226</span><span class="comment"> * that function cannot actually inline; since separates compilations are separate, the compiler command to</span></div>
<div class="line"><a id="l01227" name="l01227"></a><span class="lineno"> 1227</span><span class="comment"> * compile X.cpp has no choice but to call the real, non-inlined function (Y.cpp&#39;s own invocations of that function</span></div>
<div class="line"><a id="l01228" name="l01228"></a><span class="lineno"> 1228</span><span class="comment"> * are still inlined).  Fortunately they thought of this (eventually): link-time optimization a/k/a LTO or FLTO.</span></div>
<div class="line"><a id="l01229" name="l01229"></a><span class="lineno"> 1229</span><span class="comment"> * Essentially in this mode the linker works together with the compiler and removes this negative.</span></div>
<div class="line"><a id="l01230" name="l01230"></a><span class="lineno"> 1230</span><span class="comment"> * Unfortunately the support in compilers for this is somewhat uneven.  In my (ygoldfel) experience, clang fully</span></div>
<div class="line"><a id="l01231" name="l01231"></a><span class="lineno"> 1231</span><span class="comment"> * implements this out of the box these days, and I&#39;ve been using it on Mac delightfully; however in Linux I&#39;ve found</span></div>
<div class="line"><a id="l01232" name="l01232"></a><span class="lineno"> 1232</span><span class="comment"> * more work -- like swapping out the linker for a fancy clang-associated one -- was necessary and, while achievable,</span></div>
<div class="line"><a id="l01233" name="l01233"></a><span class="lineno"> 1233</span><span class="comment"> * I personally never spent the required time to fully achieve it.  gcc supports the feature, but it stands to reason</span></div>
<div class="line"><a id="l01234" name="l01234"></a><span class="lineno"> 1234</span><span class="comment"> * that to turn it on successfully is a multi-day project, and the newer the gcc version the easier it will probably</span></div>
<div class="line"><a id="l01235" name="l01235"></a><span class="lineno"> 1235</span><span class="comment"> * be.</span></div>
<div class="line"><a id="l01236" name="l01236"></a><span class="lineno"> 1236</span><span class="comment"> *</span></div>
<div class="line"><a id="l01237" name="l01237"></a><span class="lineno"> 1237</span><span class="comment"> * Given the last paragraph, why are we still placing the rule here?  Answer: It&#39;s a trade-off.  The positives are</span></div>
<div class="line"><a id="l01238" name="l01238"></a><span class="lineno"> 1238</span><span class="comment"> * clear and obvious; while the negative&#39;s actual perf impact is theoretically there but in practice questionable.</span></div>
<div class="line"><a id="l01239" name="l01239"></a><span class="lineno"> 1239</span><span class="comment"> * So we&#39;ve made the call to go with known positives and to deal with the negative if or when necessary in practive.</span></div>
<div class="line"><a id="l01240" name="l01240"></a><span class="lineno"> 1240</span><span class="comment"> * Since LTO exists in the compilers we use, we know the path to take when/if needed.</span></div>
<div class="line"><a id="l01241" name="l01241"></a><span class="lineno"> 1241</span><span class="comment"> *</span></div>
<div class="line"><a id="l01242" name="l01242"></a><span class="lineno"> 1242</span><span class="comment"> * Update: Now that Flow is an open-source project with a nice CI/CD pipeline, we auto-test with a number of modern</span></div>
<div class="line"><a id="l01243" name="l01243"></a><span class="lineno"> 1243</span><span class="comment"> * clang and gcc versions; all of them support LTO; and this support works just fine.  Hence the above objection</span></div>
<div class="line"><a id="l01244" name="l01244"></a><span class="lineno"> 1244</span><span class="comment"> * to the tune of &quot;uneven&quot; compiler support is no longer accurate; the support is quite good and even.</span></div>
<div class="line"><a id="l01245" name="l01245"></a><span class="lineno"> 1245</span><span class="comment"> *</span></div>
<div class="line"><a id="l01246" name="l01246"></a><span class="lineno"> 1246</span><span class="comment"> * To summarize, some may see this as a controversial rule.  We can iterate on this if someone feels strongly the</span></div>
<div class="line"><a id="l01247" name="l01247"></a><span class="lineno"> 1247</span><span class="comment"> * above logic does not stand up to scrutiny.  In terms of my (ygoldfel) experiences, which span now almost a decade,</span></div>
<div class="line"><a id="l01248" name="l01248"></a><span class="lineno"> 1248</span><span class="comment"> * the lack of full-on inlining has not been a practical perf issue.  It is even quite possible that the gains from</span></div>
<div class="line"><a id="l01249" name="l01249"></a><span class="lineno"> 1249</span><span class="comment"> * letting the compiler decide (`gcc -O3`) instead of the human constantly having to make the judgment call about what</span></div>
<div class="line"><a id="l01250" name="l01250"></a><span class="lineno"> 1250</span><span class="comment"> * to inline (`gcc -O2` + explicit inlining by dev) exceed the losses from LTO not being in effect yet.  Update:</span></div>
<div class="line"><a id="l01251" name="l01251"></a><span class="lineno"> 1251</span><span class="comment"> * with widespread LTO support in all modern gcc and clang compilers this complaint is mitigated/eliminated.] */</span></div>
<div class="line"><a id="l01252" name="l01252"></a><span class="lineno"> 1252</span> </div>
<div class="line"><a id="l01253" name="l01253"></a><span class="lineno"> 1253</span><span class="comment">// -- BEST PRACTICES: Doxygen doc header deep-dive --</span></div>
<div class="line"><a id="l01254" name="l01254"></a><span class="lineno"> 1254</span> </div>
<div class="line"><a id="l01255" name="l01255"></a><span class="lineno"> 1255</span><span class="comment">/* In &quot;BEST PRACTICES: Comments&quot; above we mentioned doc headers.  Let&#39;s get into the topic more.</span></div>
<div class="line"><a id="l01256" name="l01256"></a><span class="lineno"> 1256</span><span class="comment"> *</span></div>
<div class="line"><a id="l01257" name="l01257"></a><span class="lineno"> 1257</span><span class="comment"> * Every class/`struct`/union, function, macro, constant, variable, namespace,</span></div>
<div class="line"><a id="l01258" name="l01258"></a><span class="lineno"> 1258</span><span class="comment"> * file, exception, function parameter, template parameter, macro parameter, and anything else I forgot to list</span></div>
<div class="line"><a id="l01259" name="l01259"></a><span class="lineno"> 1259</span><span class="comment"> * MUST be accompanied by a &quot;Doxygen comment,&quot; possibly shared with one or more other items (e.g., a single</span></div>
<div class="line"><a id="l01260" name="l01260"></a><span class="lineno"> 1260</span><span class="comment"> * Doxygen comment will cover the *function* itself, each of its *parameters* and *template parameters*, and its</span></div>
<div class="line"><a id="l01261" name="l01261"></a><span class="lineno"> 1261</span><span class="comment"> * *return* value).  Run Doxygen as covered in the aforementioned README; you&#39;ve documented what you needed to</span></div>
<div class="line"><a id="l01262" name="l01262"></a><span class="lineno"> 1262</span><span class="comment"> * if any only if Doxygen does not complain, and the doc generation script finishes successfully (exit code 0).</span></div>
<div class="line"><a id="l01263" name="l01263"></a><span class="lineno"> 1263</span><span class="comment"> * A &quot;Doxygen comment&quot; is, to be clear, simply a comment with an extra one or two characters to run Doxygen&#39;s</span></div>
<div class="line"><a id="l01264" name="l01264"></a><span class="lineno"> 1264</span><span class="comment"> * attention to it: `/ * *` (sans spaces) or `///` and (usually but not always) containing Doxygen &quot;commands&quot;</span></div>
<div class="line"><a id="l01265" name="l01265"></a><span class="lineno"> 1265</span><span class="comment"> * starting with the `&quot;@&quot;` character: `&quot;@param&quot;` or `&quot;@return&quot;`.</span></div>
<div class="line"><a id="l01266" name="l01266"></a><span class="lineno"> 1266</span><span class="comment"> *</span></div>
<div class="line"><a id="l01267" name="l01267"></a><span class="lineno"> 1267</span><span class="comment"> * Do not Doxygen-document things just to say they don&#39;t exist, when that&#39;s already obvious.  Most notably, no</span></div>
<div class="line"><a id="l01268" name="l01268"></a><span class="lineno"> 1268</span><span class="comment"> * `&quot;@return&quot;` for `void` functions/methods and `void`-like functional macros.  There are probably others but just</span></div>
<div class="line"><a id="l01269" name="l01269"></a><span class="lineno"> 1269</span><span class="comment"> * follow the principle.</span></div>
<div class="line"><a id="l01270" name="l01270"></a><span class="lineno"> 1270</span><span class="comment"> *</span></div>
<div class="line"><a id="l01271" name="l01271"></a><span class="lineno"> 1271</span><span class="comment"> * Do not copy/paste documentation, unless some other constraint forces you to do so.  Instead, just refer</span></div>
<div class="line"><a id="l01272" name="l01272"></a><span class="lineno"> 1272</span><span class="comment"> * to the other documentation bit in all the instances except the 1 being referred to by others.</span></div>
<div class="line"><a id="l01273" name="l01273"></a><span class="lineno"> 1273</span><span class="comment"> * (This has its own maintenance problems, but we believe they are far outweighed by the</span></div>
<div class="line"><a id="l01274" name="l01274"></a><span class="lineno"> 1274</span><span class="comment"> * maintenance headache of copy/pasting explanatory sentences and paragraphs.)</span></div>
<div class="line"><a id="l01275" name="l01275"></a><span class="lineno"> 1275</span><span class="comment"> * This applies to all documentation, including inline comments inside function/method bodies.  Sadly, the</span></div>
<div class="line"><a id="l01276" name="l01276"></a><span class="lineno"> 1276</span><span class="comment"> * constraint that every &quot;item&quot; must have a Doxygen comment will often force you to copy/paste.  Even so,</span></div>
<div class="line"><a id="l01277" name="l01277"></a><span class="lineno"> 1277</span><span class="comment"> * do your best.  Specifically, if 4 of 5 parameters of function `f2()` use identical semantics to 4 of 7 parameters of</span></div>
<div class="line"><a id="l01278" name="l01278"></a><span class="lineno"> 1278</span><span class="comment"> * function `f1()` then -- while you ARE forced (by the &quot;every&quot; rule above) to document 4 of the 5 `f2()` parameters --</span></div>
<div class="line"><a id="l01279" name="l01279"></a><span class="lineno"> 1279</span><span class="comment"> * the body of the doc of each of the shared parameters can simply say &quot;`See f1().`&quot; instead of copy/pasting</span></div>
<div class="line"><a id="l01280" name="l01280"></a><span class="lineno"> 1280</span><span class="comment"> * its actual semantics.  This is the most prominent copy/paste situation, but the same principles can be applied</span></div>
<div class="line"><a id="l01281" name="l01281"></a><span class="lineno"> 1281</span><span class="comment"> * to others that may pop up.</span></div>
<div class="line"><a id="l01282" name="l01282"></a><span class="lineno"> 1282</span><span class="comment"> *</span></div>
<div class="line"><a id="l01283" name="l01283"></a><span class="lineno"> 1283</span><span class="comment"> * Do not use `&quot;@brief&quot;` explicily; use the first-sentence rule instead.  It&#39;s already clear by example</span></div>
<div class="line"><a id="l01284" name="l01284"></a><span class="lineno"> 1284</span><span class="comment"> * that we do not use `&quot;@brief&quot;`, but the rule that IS used is non-obvious from just looking at the code: Namely:</span></div>
<div class="line"><a id="l01285" name="l01285"></a><span class="lineno"> 1285</span><span class="comment"> * The first *sentence* of the Doxygen comment of the function/method/macro or</span></div>
<div class="line"><a id="l01286" name="l01286"></a><span class="lineno"> 1286</span><span class="comment"> * class/`struct`/union is taken as the brief description of the item.  A &quot;sentence&quot; is defined as everything up</span></div>
<div class="line"><a id="l01287" name="l01287"></a><span class="lineno"> 1287</span><span class="comment"> * to and including the first period (.).  (Watch out for &quot;a.k.a.&quot; and such: use &quot;a/k/a&quot; instead.)</span></div>
<div class="line"><a id="l01288" name="l01288"></a><span class="lineno"> 1288</span><span class="comment"> * Everything after that first sentence is the detailed description and is separated from the brief one on the</span></div>
<div class="line"><a id="l01289" name="l01289"></a><span class="lineno"> 1289</span><span class="comment"> * page (and, in many places, the brief description is present along with item name, while detailed one is</span></div>
<div class="line"><a id="l01290" name="l01290"></a><span class="lineno"> 1290</span><span class="comment"> * not there at all; for example the Class List page).  (After the description are other sub-items such as</span></div>
<div class="line"><a id="l01291" name="l01291"></a><span class="lineno"> 1291</span><span class="comment"> * `&quot;@param&quot;` or `&quot;@see&quot;` or `&quot;@todo&quot;`.)</span></div>
<div class="line"><a id="l01292" name="l01292"></a><span class="lineno"> 1292</span><span class="comment"> *</span></div>
<div class="line"><a id="l01293" name="l01293"></a><span class="lineno"> 1293</span><span class="comment"> * ### Doxygen markup within a Doxygen command ###</span></div>
<div class="line"><a id="l01294" name="l01294"></a><span class="lineno"> 1294</span><span class="comment"> * This section originally existed in the class net_flow::Node doc header, and I have left it there, because that is</span></div>
<div class="line"><a id="l01295" name="l01295"></a><span class="lineno"> 1295</span><span class="comment"> * a large class which generates a Doxygen doc page (unlike the present comment) with many examples available for</span></div>
<div class="line"><a id="l01296" name="l01296"></a><span class="lineno"> 1296</span><span class="comment"> * clarity.  Please see that doc header&#39;s identically titled subsection (&quot;Doxygen markup,&quot; etc.).</span></div>
<div class="line"><a id="l01297" name="l01297"></a><span class="lineno"> 1297</span><span class="comment"> *</span></div>
<div class="line"><a id="l01298" name="l01298"></a><span class="lineno"> 1298</span><span class="comment"> * @warning Please read it!  Also, if you intend to add to/otherwise change Doxygen-use conventions in the Flow project,</span></div>
<div class="line"><a id="l01299" name="l01299"></a><span class="lineno"> 1299</span><span class="comment"> *          please make sure you document it in that section as opposed to simply doing it and creating undocumented</span></div>
<div class="line"><a id="l01300" name="l01300"></a><span class="lineno"> 1300</span><span class="comment"> *          inconsistency (especially over time). */</span></div>
<div class="line"><a id="l01301" name="l01301"></a><span class="lineno"> 1301</span> </div>
<div class="line"><a id="l01302" name="l01302"></a><span class="lineno"> 1302</span><span class="comment">// -- BEST PRACTICES: Namespaces, libraries --</span></div>
<div class="line"><a id="l01303" name="l01303"></a><span class="lineno"> 1303</span> </div>
<div class="line"><a id="l01304" name="l01304"></a><span class="lineno"> 1304</span><span class="comment">// - Do: Use `namespace` to wrap *every* symbol in a namespace, whether public or internal. -</span></div>
<div class="line"><a id="l01305" name="l01305"></a><span class="lineno"> 1305</span> </div>
<div class="line"><a id="l01306" name="l01306"></a><span class="lineno"> 1306</span><span class="comment">/* - Corollary: Since #define macros cannot belong to any namespace, &quot;simulate&quot; it with the `NAME_SPACE_` convention. -</span></div>
<div class="line"><a id="l01307" name="l01307"></a><span class="lineno"> 1307</span><span class="comment"> *</span></div>
<div class="line"><a id="l01308" name="l01308"></a><span class="lineno"> 1308</span><span class="comment"> * namespace outer { namespace inner { [...stuff...] } }</span></div>
<div class="line"><a id="l01309" name="l01309"></a><span class="lineno"> 1309</span><span class="comment"> * #define OUTER_INNER_[...stuff...]</span></div>
<div class="line"><a id="l01310" name="l01310"></a><span class="lineno"> 1310</span><span class="comment"> *</span></div>
<div class="line"><a id="l01311" name="l01311"></a><span class="lineno"> 1311</span><span class="comment"> * Example: A class about logging in Flow: `namespace flow { namespace log { class Logger; } }</span></div>
<div class="line"><a id="l01312" name="l01312"></a><span class="lineno"> 1312</span><span class="comment"> *          A macro about logging in Flow: #define FLOW_LOG_WARNING([...]) [...] */</span></div>
<div class="line"><a id="l01313" name="l01313"></a><span class="lineno"> 1313</span> </div>
<div class="line"><a id="l01314" name="l01314"></a><span class="lineno"> 1314</span><span class="comment">// - Do: Liberally use `using a::b::thing;` inside function { bodies }. -</span></div>
<div class="line"><a id="l01315" name="l01315"></a><span class="lineno"> 1315</span><span class="comment">// - Do: Use `namespace convenient_alias = a::b;` inside function { bodies }. -</span></div>
<div class="line"><a id="l01316" name="l01316"></a><span class="lineno"> 1316</span><span class="comment">// - Corollary: Avoid: heavy explicit namespace-qualifying in function { bodies }; prefer `using` 90%+ of the time -</span></div>
<div class="line"><a id="l01317" name="l01317"></a><span class="lineno"> 1317</span> </div>
<div class="line"><a id="l01318" name="l01318"></a><span class="lineno"> 1318</span><span class="comment">// - Do not: Use file-level `using` or `using namespace`; especially never ever in headers! -</span></div>
<div class="line"><a id="l01319" name="l01319"></a><span class="lineno"> 1319</span> </div>
<div class="line"><a id="l01320" name="l01320"></a><span class="lineno"> 1320</span><span class="comment">/* - Do: Use `boost::` (Boost) or `std::` (STL) over other libraries or self-written facilities when possible -</span></div>
<div class="line"><a id="l01321" name="l01321"></a><span class="lineno"> 1321</span><span class="comment"> *</span></div>
<div class="line"><a id="l01322" name="l01322"></a><span class="lineno"> 1322</span><span class="comment"> * STL facilities by definition have a high expectation of reliability and performance, though the latter should be</span></div>
<div class="line"><a id="l01323" name="l01323"></a><span class="lineno"> 1323</span><span class="comment"> * verified for each feature when performance is paramount.  Such code is also much more portable and maintainable</span></div>
<div class="line"><a id="l01324" name="l01324"></a><span class="lineno"> 1324</span><span class="comment"> * than many of the alternatives.  Also, cppreference.com documentation is *fantastic*.</span></div>
<div class="line"><a id="l01325" name="l01325"></a><span class="lineno"> 1325</span><span class="comment"> *</span></div>
<div class="line"><a id="l01326" name="l01326"></a><span class="lineno"> 1326</span><span class="comment"> * Most STL facilities originate in Boost and then gain entry to the C++ standard and actual STL.</span></div>
<div class="line"><a id="l01327" name="l01327"></a><span class="lineno"> 1327</span><span class="comment"> * Hence Boost is considered to have equivalently high expectations of reliability, perf, *and* documentation.</span></div>
<div class="line"><a id="l01328" name="l01328"></a><span class="lineno"> 1328</span><span class="comment"> * Moreover, Boost has tons of features (in particular entire modules) not (yet) in STL. */</span></div>
<div class="line"><a id="l01329" name="l01329"></a><span class="lineno"> 1329</span> </div>
<div class="line"><a id="l01330" name="l01330"></a><span class="lineno"> 1330</span><span class="comment">/* - Corollary: Slight preference to boost:: over std:: when a given feature is equivalently in both.</span></div>
<div class="line"><a id="l01331" name="l01331"></a><span class="lineno"> 1331</span><span class="comment"> *</span></div>
<div class="line"><a id="l01332" name="l01332"></a><span class="lineno"> 1332</span><span class="comment"> * It&#39;s very common that std::...::X has boost::...::X counterpart.  In this case they&#39;re either exactly equal, or</span></div>
<div class="line"><a id="l01333" name="l01333"></a><span class="lineno"> 1333</span><span class="comment"> * the one in boost:: is a ~100% compatible super-set (equal, *plus* certain added APIs).  Either facility can be used,</span></div>
<div class="line"><a id="l01334" name="l01334"></a><span class="lineno"> 1334</span><span class="comment"> * unless you need one of the added features (e.g., boost::chrono:: equals std::chrono:: but has a thread-time clock</span></div>
<div class="line"><a id="l01335" name="l01335"></a><span class="lineno"> 1335</span><span class="comment"> * class added, among others).</span></div>
<div class="line"><a id="l01336" name="l01336"></a><span class="lineno"> 1336</span><span class="comment"> *</span></div>
<div class="line"><a id="l01337" name="l01337"></a><span class="lineno"> 1337</span><span class="comment"> * When you can use either facility, Flow leans to Boost.  A vague exception are C++03 interfaces</span></div>
<div class="line"><a id="l01338" name="l01338"></a><span class="lineno"> 1338</span><span class="comment"> * like std::string, std::vector, std::map.</span></div>
<div class="line"><a id="l01339" name="l01339"></a><span class="lineno"> 1339</span><span class="comment"> *</span></div>
<div class="line"><a id="l01340" name="l01340"></a><span class="lineno"> 1340</span><span class="comment"> * [Rationale: Honestly the latter &quot;lean&quot; is mostly a historical thing: In 2012 we were limited to C++03, so STL</span></div>
<div class="line"><a id="l01341" name="l01341"></a><span class="lineno"> 1341</span><span class="comment"> * was *much* more limited.  Since then there has been no reason to switch to std::, and several instances where</span></div>
<div class="line"><a id="l01342" name="l01342"></a><span class="lineno"> 1342</span><span class="comment"> * Boost-only features proved useful in their availability, we&#39;ve conservatively stayed with this principle.</span></div>
<div class="line"><a id="l01343" name="l01343"></a><span class="lineno"> 1343</span><span class="comment"> * Possibly if Flow were developed in 2019, we might have started off differently and would lean to std::.</span></div>
<div class="line"><a id="l01344" name="l01344"></a><span class="lineno"> 1344</span><span class="comment"> * It wasn&#39;t, so for now it is prudent to stay the course (don&#39;t fix it if it ain&#39;t broken).] */</span></div>
<div class="line"><a id="l01345" name="l01345"></a><span class="lineno"> 1345</span> </div>
<div class="line"><a id="l01346" name="l01346"></a><span class="lineno"> 1346</span><span class="comment">/* - Corollary: Use, e.g., `using Thread = &lt;std or boost&gt;::thread` for commonly used things from STL/Boost features. -</span></div>
<div class="line"><a id="l01347" name="l01347"></a><span class="lineno"> 1347</span><span class="comment"> *</span></div>
<div class="line"><a id="l01348" name="l01348"></a><span class="lineno"> 1348</span><span class="comment"> * [Rationale: 2 benefits.  One, if it&#39;s commonly used then this increases pithiness and cosmetic consistency.</span></div>
<div class="line"><a id="l01349" name="l01349"></a><span class="lineno"> 1349</span><span class="comment"> * Two, particularly for items in both STL and Boost, it makes it easy to switch the underlying implementation.] */</span></div>
<div class="line"><a id="l01350" name="l01350"></a><span class="lineno"> 1350</span> </div>
<div class="line"><a id="l01351" name="l01351"></a><span class="lineno"> 1351</span><span class="comment">/* - Do: In particular, familiarize self with these boost.* modules: -</span></div>
<div class="line"><a id="l01352" name="l01352"></a><span class="lineno"> 1352</span><span class="comment"> *</span></div>
<div class="line"><a id="l01353" name="l01353"></a><span class="lineno"> 1353</span><span class="comment"> *   Basic tools (should be familiar at minimum):</span></div>
<div class="line"><a id="l01354" name="l01354"></a><span class="lineno"> 1354</span><span class="comment"> *     any, array, chrono^, core, dynamic_bitset, lexical_cast, random*, unordered#,</span></div>
<div class="line"><a id="l01355" name="l01355"></a><span class="lineno"> 1355</span><span class="comment"> *     smart_ptr (+movelib::unique_ptr), system^, thread^&amp;, tuple, unordered, utility</span></div>
<div class="line"><a id="l01356" name="l01356"></a><span class="lineno"> 1356</span><span class="comment"> *   More advanced but similarly uncontroversial:</span></div>
<div class="line"><a id="l01357" name="l01357"></a><span class="lineno"> 1357</span><span class="comment"> *     atomic$, date_time, filesystem, heap, ratio, stacktrace, timer, tribool</span></div>
<div class="line"><a id="l01358" name="l01358"></a><span class="lineno"> 1358</span><span class="comment"> *   Advanced and should be decided on with care; but institutionally known to be solid:</span></div>
<div class="line"><a id="l01359" name="l01359"></a><span class="lineno"> 1359</span><span class="comment"> *     asio%, format, interprocess, intrusive, io, iostreams, program_options, regex, algorithms, string_algo@</span></div>
<div class="line"><a id="l01360" name="l01360"></a><span class="lineno"> 1360</span><span class="comment"> *   No personal or institutional experience; advanced; should be looked into opportunistically:</span></div>
<div class="line"><a id="l01361" name="l01361"></a><span class="lineno"> 1361</span><span class="comment"> *     context, couroutine2, fiber - Relates to &quot;micro-thread&quot; concept.</span></div>
<div class="line"><a id="l01362" name="l01362"></a><span class="lineno"> 1362</span><span class="comment"> *     exception - Also see guidelines re. exceptions elsewhere in this doc.</span></div>
<div class="line"><a id="l01363" name="l01363"></a><span class="lineno"> 1363</span><span class="comment"> *     beast - Write HTTP-WebSocket-... servers, on top of boost.asio.</span></div>
<div class="line"><a id="l01364" name="l01364"></a><span class="lineno"> 1364</span><span class="comment"> *     pool</span></div>
<div class="line"><a id="l01365" name="l01365"></a><span class="lineno"> 1365</span><span class="comment"> *     log - Flow has its own flow::log framework.  A top-level doc header discusses why using that and not boost.log.</span></div>
<div class="line"><a id="l01366" name="l01366"></a><span class="lineno"> 1366</span><span class="comment"> *   Do not use:</span></div>
<div class="line"><a id="l01367" name="l01367"></a><span class="lineno"> 1367</span><span class="comment"> *     function!</span></div>
<div class="line"><a id="l01368" name="l01368"></a><span class="lineno"> 1368</span><span class="comment"> *</span></div>
<div class="line"><a id="l01369" name="l01369"></a><span class="lineno"> 1369</span><span class="comment"> * -%- First see flow::async::..., which provides the most convenient way to work in the boost.asio style.</span></div>
<div class="line"><a id="l01370" name="l01370"></a><span class="lineno"> 1370</span><span class="comment"> * -*- See also Flow&#39;s random.hpp.</span></div>
<div class="line"><a id="l01371" name="l01371"></a><span class="lineno"> 1371</span><span class="comment"> * -#- See also flow::util::Linked_hash_{map|set}.</span></div>
<div class="line"><a id="l01372" name="l01372"></a><span class="lineno"> 1372</span><span class="comment"> * -^- Check out the flow:: public `using` aliases for stuff inside these modules.</span></div>
<div class="line"><a id="l01373" name="l01373"></a><span class="lineno"> 1373</span><span class="comment"> * -&amp;- Also: There&#39;s a long-standing ticket about the slowness of boost::shared_mutex (sans contention) even as of</span></div>
<div class="line"><a id="l01374" name="l01374"></a><span class="lineno"> 1374</span><span class="comment"> *     Boost-1.80.  It might be better to use std::shared_mutex.  However consider that experts say a regular</span></div>
<div class="line"><a id="l01375" name="l01375"></a><span class="lineno"> 1375</span><span class="comment"> *     mutex is blindingly fast to lock/unlock, and thus any `shared_mutex` is only &quot;worth it&quot; with long read</span></div>
<div class="line"><a id="l01376" name="l01376"></a><span class="lineno"> 1376</span><span class="comment"> *     critical sections and their very frequent invocation; this is apparently quite rare.</span></div>
<div class="line"><a id="l01377" name="l01377"></a><span class="lineno"> 1377</span><span class="comment"> * -@- Be very careful about performance.  Lib is highly generic and might be too slow in some contexts (&lt;-experience).</span></div>
<div class="line"><a id="l01378" name="l01378"></a><span class="lineno"> 1378</span><span class="comment"> * -$- Performance-sensitive; perf bake-off vs. std:: might be relevant in some cases.</span></div>
<div class="line"><a id="l01379" name="l01379"></a><span class="lineno"> 1379</span><span class="comment"> *     Update: Current (8/2023) wisdom appears to be to possibly prefer std::atomic to boost::atomic; suspecting</span></div>
<div class="line"><a id="l01380" name="l01380"></a><span class="lineno"> 1380</span><span class="comment"> *     better or at least not-worse perf due to native nature of it.  It can go either way; but current preference</span></div>
<div class="line"><a id="l01381" name="l01381"></a><span class="lineno"> 1381</span><span class="comment"> *     in Flow has switched to std::atomic.  (A perf bake-off might be nice, but std::atomic really should be safe</span></div>
<div class="line"><a id="l01382" name="l01382"></a><span class="lineno"> 1382</span><span class="comment"> *     and full-featured.)</span></div>
<div class="line"><a id="l01383" name="l01383"></a><span class="lineno"> 1383</span><span class="comment"> * -!- boost.function is, it turns out, horrendously slow (too much capture copying).  Plus it has a 10-arg limit.</span></div>
<div class="line"><a id="l01384" name="l01384"></a><span class="lineno"> 1384</span><span class="comment"> *     std::function in gcc looks great in both regards though lacking some very minor APIs from boost.function.</span></div>
<div class="line"><a id="l01385" name="l01385"></a><span class="lineno"> 1385</span><span class="comment"> *     Just use flow::Function: it&#39;s the best of both worlds.  Definitely do not use boost.function! */</span></div>
<div class="line"><a id="l01386" name="l01386"></a><span class="lineno"> 1386</span> </div>
<div class="line"><a id="l01387" name="l01387"></a><span class="lineno"> 1387</span><span class="comment">// -- BEST PRACTICES: Error handling --</span></div>
<div class="line"><a id="l01388" name="l01388"></a><span class="lineno"> 1388</span> </div>
<div class="line"><a id="l01389" name="l01389"></a><span class="lineno"> 1389</span><span class="comment">// - Do: Use assert() for bad arg values as much as possible *unless* returning an error is worth it to user. -</span></div>
<div class="line"><a id="l01390" name="l01390"></a><span class="lineno"> 1390</span><span class="comment">// - Do: Use static_assert() for compile-time checks, or after failing an #if[def] (or other) compile-time check. -</span></div>
<div class="line"><a id="l01391" name="l01391"></a><span class="lineno"> 1391</span><span class="comment">/* - Do not: Use `#error &quot;&lt;message&gt;&quot;` after failing an #if[def] (or other) compile-time check. -</span></div>
<div class="line"><a id="l01392" name="l01392"></a><span class="lineno"> 1392</span><span class="comment"> *</span></div>
<div class="line"><a id="l01393" name="l01393"></a><span class="lineno"> 1393</span><span class="comment"> * `static_assert(false, &quot;&lt;message&gt;&quot;)` is quite a bit more convenient. */</span></div>
<div class="line"><a id="l01394" name="l01394"></a><span class="lineno"> 1394</span><span class="comment">// - Do: Use `if constexpr()` for compile-time checks. -</span></div>
<div class="line"><a id="l01395" name="l01395"></a><span class="lineno"> 1395</span><span class="comment">/* - Avoid: using SFINAE (look it up please) -- when possible. -</span></div>
<div class="line"><a id="l01396" name="l01396"></a><span class="lineno"> 1396</span><span class="comment"> *</span></div>
<div class="line"><a id="l01397" name="l01397"></a><span class="lineno"> 1397</span><span class="comment"> * SFINAE is tough to comprehend and code. `if constexpr()` often makes it unnecessary and is much easier</span></div>
<div class="line"><a id="l01398" name="l01398"></a><span class="lineno"> 1398</span><span class="comment"> * to follow and code. */</span></div>
<div class="line"><a id="l01399" name="l01399"></a><span class="lineno"> 1399</span> </div>
<div class="line"><a id="l01400" name="l01400"></a><span class="lineno"> 1400</span><span class="comment">/* - Do: Use Flow&#39;s standard error reporting convention/boiler-plate when returning errors from a public lib API. -</span></div>
<div class="line"><a id="l01401" name="l01401"></a><span class="lineno"> 1401</span><span class="comment"> *</span></div>
<div class="line"><a id="l01402" name="l01402"></a><span class="lineno"> 1402</span><span class="comment"> * This allows for returning both error codes (boost.system ones) for high perf *and* optionally wrapping that in</span></div>
<div class="line"><a id="l01403" name="l01403"></a><span class="lineno"> 1403</span><span class="comment"> * an exception if so desired.  Read more starting in flow::Error_error code doc header.  See also some notes on error</span></div>
<div class="line"><a id="l01404" name="l01404"></a><span class="lineno"> 1404</span><span class="comment"> * reporting in common.hpp. */</span></div>
<div class="line"><a id="l01405" name="l01405"></a><span class="lineno"> 1405</span> </div>
<div class="line"><a id="l01406" name="l01406"></a><span class="lineno"> 1406</span><span class="comment">/* - Do: ...follow the following thoughts when considering using exceptions or not. -</span></div>
<div class="line"><a id="l01407" name="l01407"></a><span class="lineno"> 1407</span><span class="comment"> *</span></div>
<div class="line"><a id="l01408" name="l01408"></a><span class="lineno"> 1408</span><span class="comment"> * Question 1 is whether to optionally throw an exception on error at the *top* level of a given *public* *libary* API.</span></div>
<div class="line"><a id="l01409" name="l01409"></a><span class="lineno"> 1409</span><span class="comment"> * That&#39;s covered in the previous guideline.  Here we talk about whether to throw exceptions *throughout* the</span></div>
<div class="line"><a id="l01410" name="l01410"></a><span class="lineno"> 1410</span><span class="comment"> * implementation, which is a different question.  So, suppose an error has been detected.  Then:</span></div>
<div class="line"><a id="l01411" name="l01411"></a><span class="lineno"> 1411</span><span class="comment"> *</span></div>
<div class="line"><a id="l01412" name="l01412"></a><span class="lineno"> 1412</span><span class="comment"> * Basic fact: Fastest is to assert().  Sometimes that&#39;s not sufficient for obvious reasons.  If so:</span></div>
<div class="line"><a id="l01413" name="l01413"></a><span class="lineno"> 1413</span><span class="comment"> * Basic fact: Next fastest is, on error, to return an Error_code (or just a `bool` or similar, if truly sufficient).</span></div>
<div class="line"><a id="l01414" name="l01414"></a><span class="lineno"> 1414</span><span class="comment"> *   This is very fast; it&#39;s just like returning an `int` (it&#39;s a couple of `int`s really internally but close enough).</span></div>
<div class="line"><a id="l01415" name="l01415"></a><span class="lineno"> 1415</span><span class="comment"> * Basic fact: Finally, you can throw an exception.  This should be considered slow, and I leave it at that for</span></div>
<div class="line"><a id="l01416" name="l01416"></a><span class="lineno"> 1416</span><span class="comment"> *   simplicity.</span></div>
<div class="line"><a id="l01417" name="l01417"></a><span class="lineno"> 1417</span><span class="comment"> * HUGELY KEY FACT: *Not* throwing an exception (meaning no error was detected) is *just* as fast as returning</span></div>
<div class="line"><a id="l01418" name="l01418"></a><span class="lineno"> 1418</span><span class="comment"> *   a success code / false / zero / etc.  A tiny-tiny bit faster even.  A *potential* exception -- or 500 potential</span></div>
<div class="line"><a id="l01419" name="l01419"></a><span class="lineno"> 1419</span><span class="comment"> *   exceptions in a given call tree -- has zero perf cost, period.</span></div>
<div class="line"><a id="l01420" name="l01420"></a><span class="lineno"> 1420</span><span class="comment"> *</span></div>
<div class="line"><a id="l01421" name="l01421"></a><span class="lineno"> 1421</span><span class="comment"> * Therefore this somewhat vague guideline: Avoid exceptions in internal implementations, as then there&#39;s no perf</span></div>
<div class="line"><a id="l01422" name="l01422"></a><span class="lineno"> 1422</span><span class="comment"> * question.  However, it may be very convenient to throw an exception sometimes; the stack unwinds and can make</span></div>
<div class="line"><a id="l01423" name="l01423"></a><span class="lineno"> 1423</span><span class="comment"> * some code so much simpler.  Then, consider using an exception... and do so if you can very confidently state this</span></div>
<div class="line"><a id="l01424" name="l01424"></a><span class="lineno"> 1424</span><span class="comment"> * will *not* cause a high rate of exceptions thrown in reality.  If there&#39;s any question about that, lean to avoiding</span></div>
<div class="line"><a id="l01425" name="l01425"></a><span class="lineno"> 1425</span><span class="comment"> * exception code paths after all.  If there isn&#39;t, feel free.  For example, as of this writing there are only a</span></div>
<div class="line"><a id="l01426" name="l01426"></a><span class="lineno"> 1426</span><span class="comment"> * small handful of such places in Flow, but they do exist.</span></div>
<div class="line"><a id="l01427" name="l01427"></a><span class="lineno"> 1427</span><span class="comment"> *</span></div>
<div class="line"><a id="l01428" name="l01428"></a><span class="lineno"> 1428</span><span class="comment"> * See also some notes on internally thrown exceptions in common.hpp. */</span></div>
<div class="line"><a id="l01429" name="l01429"></a><span class="lineno"> 1429</span> </div>
<div class="line"><a id="l01430" name="l01430"></a><span class="lineno"> 1430</span><span class="comment">// -- BEST PRACTICES: Logging --</span></div>
<div class="line"><a id="l01431" name="l01431"></a><span class="lineno"> 1431</span> </div>
<div class="line"><a id="l01432" name="l01432"></a><span class="lineno"> 1432</span><span class="comment">/* - Log as much as possible and practical.  If verbosity+perf is a concern, just use the appropriate log::Sev. -</span></div>
<div class="line"><a id="l01433" name="l01433"></a><span class="lineno"> 1433</span><span class="comment"> *</span></div>
<div class="line"><a id="l01434" name="l01434"></a><span class="lineno"> 1434</span><span class="comment"> * Do have some concern for the visual experience of reading the logs (shouldn&#39;t be TOO redundant and wordy).</span></div>
<div class="line"><a id="l01435" name="l01435"></a><span class="lineno"> 1435</span><span class="comment"> * [Rationale: Debuggers are great... but not always available when you need them.  Logging is superior to</span></div>
<div class="line"><a id="l01436" name="l01436"></a><span class="lineno"> 1436</span><span class="comment"> * relying on debuggers in almost every way; in many cases it even avoids the need to reproduce problem/bug, as it</span></div>
<div class="line"><a id="l01437" name="l01437"></a><span class="lineno"> 1437</span><span class="comment"> * can often be solved by looking at the logs.  Even if not, it&#39;s much easier to turn up verbosity and reproduce than</span></div>
<div class="line"><a id="l01438" name="l01438"></a><span class="lineno"> 1438</span><span class="comment"> * to attach a debugger or examine a core file.  The famous K&amp;R C book makes this wonderful, correct point.] */</span></div>
<div class="line"><a id="l01439" name="l01439"></a><span class="lineno"> 1439</span> </div>
<div class="line"><a id="l01440" name="l01440"></a><span class="lineno"> 1440</span><span class="comment">// -- BEST PRACTICES: Types and type safety --</span></div>
<div class="line"><a id="l01441" name="l01441"></a><span class="lineno"> 1441</span> </div>
<div class="line"><a id="l01442" name="l01442"></a><span class="lineno"> 1442</span><span class="comment">/* - Do: Always ensure total const-correctness. -</span></div>
<div class="line"><a id="l01443" name="l01443"></a><span class="lineno"> 1443</span><span class="comment"> *</span></div>
<div class="line"><a id="l01444" name="l01444"></a><span class="lineno"> 1444</span><span class="comment"> * [Rationale: Probably most/all coders are familiar with this and likely agree.  But this is a const-correct shop,</span></div>
<div class="line"><a id="l01445" name="l01445"></a><span class="lineno"> 1445</span><span class="comment"> * no exceptions, outside of working with ill-behaved outside libraries which may not be const-correct.] */</span></div>
<div class="line"><a id="l01446" name="l01446"></a><span class="lineno"> 1446</span> </div>
<div class="line"><a id="l01447" name="l01447"></a><span class="lineno"> 1447</span><span class="comment">/* - Corollary: Do not: use C-style casts; const|reinterpret_cast&lt;&gt; are to be rare and always justified w/ comment. -</span></div>
<div class="line"><a id="l01448" name="l01448"></a><span class="lineno"> 1448</span><span class="comment"> *</span></div>
<div class="line"><a id="l01449" name="l01449"></a><span class="lineno"> 1449</span><span class="comment"> * [Rationale: C-style cast, like `(T)x`, is always bad, as it allows type-unsafety and const-discarding without</span></div>
<div class="line"><a id="l01450" name="l01450"></a><span class="lineno"> 1450</span><span class="comment"> * even clearly doing so.  Instead, use `static|dynamic|reinterpret|const_cast`, with the latter 2 used rarely</span></div>
<div class="line"><a id="l01451" name="l01451"></a><span class="lineno"> 1451</span><span class="comment"> * when it is required to be type-unsafe and const-incorrect respectively.  Hence explain why you&#39;re doing it in those</span></div>
<div class="line"><a id="l01452" name="l01452"></a><span class="lineno"> 1452</span><span class="comment"> * cases.] */</span></div>
<div class="line"><a id="l01453" name="l01453"></a><span class="lineno"> 1453</span> </div>
<div class="line"><a id="l01454" name="l01454"></a><span class="lineno"> 1454</span><span class="comment">/* - Do: Learn lambdas ASAP.  Use them extensively.  There should be NO reason to use bind() or a functor. -</span></div>
<div class="line"><a id="l01455" name="l01455"></a><span class="lineno"> 1455</span><span class="comment"> *</span></div>
<div class="line"><a id="l01456" name="l01456"></a><span class="lineno"> 1456</span><span class="comment"> * [Rationale: Can wax poetic here, but it&#39;s best understood by experience.  One sees the advantages quickly.</span></div>
<div class="line"><a id="l01457" name="l01457"></a><span class="lineno"> 1457</span><span class="comment"> * Basically, lambdas are pithy, fast, and flexible ways to create function objects which is a constant need in</span></div>
<div class="line"><a id="l01458" name="l01458"></a><span class="lineno"> 1458</span><span class="comment"> * modern C++.  bind() was SPECTACULAR in C++03, but with C++11 lambdas its use cases are mainly subsumed, adding</span></div>
<div class="line"><a id="l01459" name="l01459"></a><span class="lineno"> 1459</span><span class="comment"> * not only clarity but performance (compiler is much more likely to inline/optimize cleverly, as it&#39;s a built-in</span></div>
<div class="line"><a id="l01460" name="l01460"></a><span class="lineno"> 1460</span><span class="comment"> * language feature and not a crazy feature built in the library via C++ generic trickery).] */</span></div>
<div class="line"><a id="l01461" name="l01461"></a><span class="lineno"> 1461</span><span class="comment">// - Corollary: Async code flows can be expressed readably, helping resolve the biggest prob with async code flows. -</span></div>
<div class="line"><a id="l01462" name="l01462"></a><span class="lineno"> 1462</span> </div>
<div class="line"><a id="l01463" name="l01463"></a><span class="lineno"> 1463</span><span class="comment">// - Do not: Use #define macros for constants.  Use typed `const`s. - [Rationale: Better for debugging, type safety.]</span></div>
<div class="line"><a id="l01464" name="l01464"></a><span class="lineno"> 1464</span><span class="comment">// - Corollary: Non-functional macros (#define without `()`) must be very rare, such as for an efficient logging API. -</span></div>
<div class="line"><a id="l01465" name="l01465"></a><span class="lineno"> 1465</span> </div>
<div class="line"><a id="l01466" name="l01466"></a><span class="lineno"> 1466</span><span class="comment">/* - Avoid: functional macros, period. -</span></div>
<div class="line"><a id="l01467" name="l01467"></a><span class="lineno"> 1467</span><span class="comment"> *</span></div>
<div class="line"><a id="l01468" name="l01468"></a><span class="lineno"> 1468</span><span class="comment"> * See if it can be done with a function with minimal loss of syntactic sugar.  [Rationale: Debugging, type safety.]</span></div>
<div class="line"><a id="l01469" name="l01469"></a><span class="lineno"> 1469</span><span class="comment"> * If there is syntactic sugar lost that is absolutely essential, write as much as possible in a function; then wrap</span></div>
<div class="line"><a id="l01470" name="l01470"></a><span class="lineno"> 1470</span><span class="comment"> * that in a functional #define to add the necessary syntactic sugar.  (Example: __FILE__, __LINE__, __FUNCTION__</span></div>
<div class="line"><a id="l01471" name="l01471"></a><span class="lineno"> 1471</span><span class="comment"> * are often auto-logged in logging APIs; a macro is needed to add these automatically at log call sites without</span></div>
<div class="line"><a id="l01472" name="l01472"></a><span class="lineno"> 1472</span><span class="comment"> * coder having to do so every time.) */</span></div>
<div class="line"><a id="l01473" name="l01473"></a><span class="lineno"> 1473</span> </div>
<div class="line"><a id="l01474" name="l01474"></a><span class="lineno"> 1474</span><span class="comment">// - Corollary: Functional macros used in a local chunk of one file should be #undef`ed. -</span></div>
<div class="line"><a id="l01475" name="l01475"></a><span class="lineno"> 1475</span> </div>
<div class="line"><a id="l01476" name="l01476"></a><span class="lineno"> 1476</span><span class="comment">// - Do: Use `const T&amp;` for performance (instead of `T`) when relevant. -</span></div>
<div class="line"><a id="l01477" name="l01477"></a><span class="lineno"> 1477</span> </div>
<div class="line"><a id="l01478" name="l01478"></a><span class="lineno"> 1478</span><span class="comment">/* - Avoid: Using non-const `T&amp;` function args (use T* instead). -</span></div>
<div class="line"><a id="l01479" name="l01479"></a><span class="lineno"> 1479</span><span class="comment"> *</span></div>
<div class="line"><a id="l01480" name="l01480"></a><span class="lineno"> 1480</span><span class="comment"> * Hence if you have an out-arg of type T, take a pointer to T, not a reference to T.  (You can easily alias it to</span></div>
<div class="line"><a id="l01481" name="l01481"></a><span class="lineno"> 1481</span><span class="comment"> * a reference T&amp; inside the function, if you like it for syntactic sugar.)  If it can be null, you can use that as</span></div>
<div class="line"><a id="l01482" name="l01482"></a><span class="lineno"> 1482</span><span class="comment"> * a semantic tidbit meaning &quot;turn off the feature to do with this arg&quot;; if there&#39;s no need then just assert() it&#39;s not</span></div>
<div class="line"><a id="l01483" name="l01483"></a><span class="lineno"> 1483</span><span class="comment"> * null and move on.</span></div>
<div class="line"><a id="l01484" name="l01484"></a><span class="lineno"> 1484</span><span class="comment"> *</span></div>
<div class="line"><a id="l01485" name="l01485"></a><span class="lineno"> 1485</span><span class="comment"> * Hence, when calling a function and passing an out-arg, it&#39;ll commonly look like: cool_func(&amp;modified_obj);</span></div>
<div class="line"><a id="l01486" name="l01486"></a><span class="lineno"> 1486</span><span class="comment"> * That&#39;s instead of: cool_func(modified_obj);</span></div>
<div class="line"><a id="l01487" name="l01487"></a><span class="lineno"> 1487</span><span class="comment"> *</span></div>
<div class="line"><a id="l01488" name="l01488"></a><span class="lineno"> 1488</span><span class="comment"> * [Rationale: This might be surprising, as vast majority of coders (including STL, Boost) use non-const ref out-args.</span></div>
<div class="line"><a id="l01489" name="l01489"></a><span class="lineno"> 1489</span><span class="comment"> * This guideline may seem controversial (and it is, after all, optional though strongly encouraged) but consider this:</span></div>
<div class="line"><a id="l01490" name="l01490"></a><span class="lineno"> 1490</span><span class="comment"> *   - Using a pointer is no slower.  assert() (if applicable) costs little to nothing.</span></div>
<div class="line"><a id="l01491" name="l01491"></a><span class="lineno"> 1491</span><span class="comment"> *   - Using a pointer makes the call site *much* more expressive: You can see a thing may be modified.</span></div>
<div class="line"><a id="l01492" name="l01492"></a><span class="lineno"> 1492</span><span class="comment"> *     Makes algorithm easier to understand at a glance.</span></div>
<div class="line"><a id="l01493" name="l01493"></a><span class="lineno"> 1493</span><span class="comment"> *   - Using a pointer provides an easy way to &quot;turn off&quot; the arg which is commonly needed though of course not</span></div>
<div class="line"><a id="l01494" name="l01494"></a><span class="lineno"> 1494</span><span class="comment"> *     universal.  When so used, the API is usually pithier than the alternative (requiring another arg, or a special</span></div>
<div class="line"><a id="l01495" name="l01495"></a><span class="lineno"> 1495</span><span class="comment"> *     value, or something).  For example, see how Flow&#39;s lib-API-error-returning convention works:</span></div>
<div class="line"><a id="l01496" name="l01496"></a><span class="lineno"> 1496</span><span class="comment"> *     if you pass in `Error_code* ec = null`, it&#39;ll throw exception on error; else it&#39;ll return normally and set</span></div>
<div class="line"><a id="l01497" name="l01497"></a><span class="lineno"> 1497</span><span class="comment"> *     *ec accordingly (including setting it no-error on success).</span></div>
<div class="line"><a id="l01498" name="l01498"></a><span class="lineno"> 1498</span><span class="comment"> * Try it.  You might like it.]</span></div>
<div class="line"><a id="l01499" name="l01499"></a><span class="lineno"> 1499</span><span class="comment"> *</span></div>
<div class="line"><a id="l01500" name="l01500"></a><span class="lineno"> 1500</span><span class="comment"> * Not a hard rule.  In particular, `ostream&amp; os` is a common arg form by convention from STL and Boost.  Use your</span></div>
<div class="line"><a id="l01501" name="l01501"></a><span class="lineno"> 1501</span><span class="comment"> * judgment. */</span></div>
<div class="line"><a id="l01502" name="l01502"></a><span class="lineno"> 1502</span> </div>
<div class="line"><a id="l01503" name="l01503"></a><span class="lineno"> 1503</span><span class="comment">// -- BEST PRACTICES: General design do&#39;s and don&#39;ts --</span></div>
<div class="line"><a id="l01504" name="l01504"></a><span class="lineno"> 1504</span> </div>
<div class="line"><a id="l01505" name="l01505"></a><span class="lineno"> 1505</span><span class="comment">/* - Do: Use inheritance for &quot;is-a&quot; interfaces, as in Java interfaces (no, or very little, non-pure-virtual content). -</span></div>
<div class="line"><a id="l01506" name="l01506"></a><span class="lineno"> 1506</span><span class="comment"> *</span></div>
<div class="line"><a id="l01507" name="l01507"></a><span class="lineno"> 1507</span><span class="comment"> * Class A = interface; describes how to use it as *only* 1+ pure virtual methods.</span></div>
<div class="line"><a id="l01508" name="l01508"></a><span class="lineno"> 1508</span><span class="comment"> * Classes B, C = concrete types: Each B or C &quot;is-an&quot; A, so they use public inheritance B-&gt;A&lt;-C. */</span></div>
<div class="line"><a id="l01509" name="l01509"></a><span class="lineno"> 1509</span><span class="comment">/* - Corollary: With wide-spread use of such interfaces, multiple inheritance becomes wide-spread... yet simple, as</span></div>
<div class="line"><a id="l01510" name="l01510"></a><span class="lineno"> 1510</span><span class="comment"> *   one inherits only pure virtual method signatures and nothing else. - */</span></div>
<div class="line"><a id="l01511" name="l01511"></a><span class="lineno"> 1511</span> </div>
<div class="line"><a id="l01512" name="l01512"></a><span class="lineno"> 1512</span><span class="comment">/* - Do: Use inheritance when adding capabilities to an existing concrete class, a/k/a &quot;is-a&quot; inheritance. -</span></div>
<div class="line"><a id="l01513" name="l01513"></a><span class="lineno"> 1513</span><span class="comment"> *</span></div>
<div class="line"><a id="l01514" name="l01514"></a><span class="lineno"> 1514</span><span class="comment"> * Class A = concrete class with capabilies X.</span></div>
<div class="line"><a id="l01515" name="l01515"></a><span class="lineno"> 1515</span><span class="comment"> * Class B `public`ly inherits B-&gt;A and adds capabilities Y.  Therefore, B &quot;is-an&quot; A, plus it adds more capabilities</span></div>
<div class="line"><a id="l01516" name="l01516"></a><span class="lineno"> 1516</span><span class="comment"> * on top.  (This can of course continue indefinitely.  C can subclass B and add more stuff; etc. */</span></div>
<div class="line"><a id="l01517" name="l01517"></a><span class="lineno"> 1517</span> </div>
<div class="line"><a id="l01518" name="l01518"></a><span class="lineno"> 1518</span><span class="comment">/* - Avoid: Using inheritance to provide common capabilities to 2+ subclasses. -</span></div>
<div class="line"><a id="l01519" name="l01519"></a><span class="lineno"> 1519</span><span class="comment"> * - Instead: Use composition. -</span></div>
<div class="line"><a id="l01520" name="l01520"></a><span class="lineno"> 1520</span><span class="comment"> *</span></div>
<div class="line"><a id="l01521" name="l01521"></a><span class="lineno"> 1521</span><span class="comment"> * Composition = put common capabilities into a separate class; then instantiate data member(s) and/or local</span></div>
<div class="line"><a id="l01522" name="l01522"></a><span class="lineno"> 1522</span><span class="comment"> * variable(s) of that type; no need to derive from that type usually.</span></div>
<div class="line"><a id="l01523" name="l01523"></a><span class="lineno"> 1523</span><span class="comment"></span> </div>
<div class="line"><a id="l01524" name="l01524"></a><span class="lineno"> 1524</span><span class="comment"> * Two techniques are pretty common but should be avoided.</span></div>
<div class="line"><a id="l01525" name="l01525"></a><span class="lineno"> 1525</span><span class="comment"> *   - Classes B and C need common, stateful capabilities in class A.  Therefore, use `private` inheritance B-&gt;A&lt;-C.</span></div>
<div class="line"><a id="l01526" name="l01526"></a><span class="lineno"> 1526</span><span class="comment"> *     Instead: Instantiate A in B and C, as needed (composition).</span></div>
<div class="line"><a id="l01527" name="l01527"></a><span class="lineno"> 1527</span><span class="comment"> *   - Classes B and C implement interface A.  Therefore, use `public` B-&gt;A&lt;-C... *but also* B and C need</span></div>
<div class="line"><a id="l01528" name="l01528"></a><span class="lineno"> 1528</span><span class="comment"> *     common, stateful capabilities.  Therefore, add those capabilities into A as well making it not a clean interface.</span></div>
<div class="line"><a id="l01529" name="l01529"></a><span class="lineno"> 1529</span><span class="comment"> *     Instead: Keep the interface class A clean; create separate class A&#39; with the common, stateful capabilities;</span></div>
<div class="line"><a id="l01530" name="l01530"></a><span class="lineno"> 1530</span><span class="comment"> *     then instantiate A&#39; in B and C, as needed (composition).</span></div>
<div class="line"><a id="l01531" name="l01531"></a><span class="lineno"> 1531</span><span class="comment"> *</span></div>
<div class="line"><a id="l01532" name="l01532"></a><span class="lineno"> 1532</span><span class="comment"> * *Not* a hard rule, but considering it before going ahead with non-interface-y inheritance = good design instinct.</span></div>
<div class="line"><a id="l01533" name="l01533"></a><span class="lineno"> 1533</span><span class="comment"> *</span></div>
<div class="line"><a id="l01534" name="l01534"></a><span class="lineno"> 1534</span><span class="comment"> * [Rationale: For me (ygoldfel), this lesson took 10+ years to learn.  It is much more pleasant and flexible.</span></div>
<div class="line"><a id="l01535" name="l01535"></a><span class="lineno"> 1535</span><span class="comment"> * Using inheritance for this tends to be the result of not cleanly separating the notion of &quot;common interface&quot; (primary</span></div>
<div class="line"><a id="l01536" name="l01536"></a><span class="lineno"> 1536</span><span class="comment"> * purpose of inheritance) from that of &quot;common concrete code&quot; (typically easily done with composition).</span></div>
<div class="line"><a id="l01537" name="l01537"></a><span class="lineno"> 1537</span><span class="comment"> * There&#39;s also a certain beauty to a B-&gt;A&lt;-C relationship that tightly helps B and C reuse complex code stored in A,</span></div>
<div class="line"><a id="l01538" name="l01538"></a><span class="lineno"> 1538</span><span class="comment"> * while B and C don&#39;t care about each other.  What I&#39;ve learned over a long time is that this satisfaction becomes</span></div>
<div class="line"><a id="l01539" name="l01539"></a><span class="lineno"> 1539</span><span class="comment"> * fleeting, when one has to tweak something about B-&gt;A or C-&gt;A, and suddenly one has to rejigger the whole setup.</span></div>
<div class="line"><a id="l01540" name="l01540"></a><span class="lineno"> 1540</span><span class="comment"> * Composition (where A is instantiated by each of B and C) helps make that process much simpler.</span></div>
<div class="line"><a id="l01541" name="l01541"></a><span class="lineno"> 1541</span><span class="comment"> * Among other things, A can be constructed/destroyed anytime; instantiated 2+ times simultaneously; etc.] */</span></div>
<div class="line"><a id="l01542" name="l01542"></a><span class="lineno"> 1542</span> </div>
<div class="line"><a id="l01543" name="l01543"></a><span class="lineno"> 1543</span><span class="comment">/* - Corollary: `protected` non-pure non-`static` methods and `const` data members are OK, but consider composition. -</span></div>
<div class="line"><a id="l01544" name="l01544"></a><span class="lineno"> 1544</span><span class="comment"></span> </div>
<div class="line"><a id="l01545" name="l01545"></a><span class="lineno"> 1545</span><span class="comment">/* - Do not: use `protected` non-`const` data members (member of A, with inheritance B-&gt;A)! -</span></div>
<div class="line"><a id="l01546" name="l01546"></a><span class="lineno"> 1546</span><span class="comment"> *</span></div>
<div class="line"><a id="l01547" name="l01547"></a><span class="lineno"> 1547</span><span class="comment"> * This breaks encapsulation; A is best designed to be self-contained; giving direct mutable access to B allows it to</span></div>
<div class="line"><a id="l01548" name="l01548"></a><span class="lineno"> 1548</span><span class="comment"> * break invariants of A; so now basically A and B become inter-related and must be maintained together, tightly</span></div>
<div class="line"><a id="l01549" name="l01549"></a><span class="lineno"> 1549</span><span class="comment"> * coupled.</span></div>
<div class="line"><a id="l01550" name="l01550"></a><span class="lineno"> 1550</span><span class="comment"> *</span></div>
<div class="line"><a id="l01551" name="l01551"></a><span class="lineno"> 1551</span><span class="comment"> * Can&#39;t you just &quot;cheat&quot; by wrapping the access into a non-`const`-reference-returning `protected` accessor or</span></div>
<div class="line"><a id="l01552" name="l01552"></a><span class="lineno"> 1552</span><span class="comment"> * something?  Well, yes, but then you&#39;re still breaking the spirit of the guideline.  The spirit is the point.</span></div>
<div class="line"><a id="l01553" name="l01553"></a><span class="lineno"> 1553</span><span class="comment"> * Still, a protected method or accessor (if you must) is still better. */</span></div>
<div class="line"><a id="l01554" name="l01554"></a><span class="lineno"> 1554</span> </div>
<div class="line"><a id="l01555" name="l01555"></a><span class="lineno"> 1555</span> </div>
<div class="line"><a id="l01556" name="l01556"></a><span class="lineno"> 1556</span><span class="comment">/* - Do: Use the `_base` inheritance pattern when a T-parameterized class template C contains non-T-parameterized</span></div>
<div class="line"><a id="l01557" name="l01557"></a><span class="lineno"> 1557</span><span class="comment"> *   aliases/constants/etc. that must be usable without actually instantiating the template C&lt;T&gt; for some concrete</span></div>
<div class="line"><a id="l01558" name="l01558"></a><span class="lineno"> 1558</span><span class="comment"> *   `T`. -</span></div>
<div class="line"><a id="l01559" name="l01559"></a><span class="lineno"> 1559</span><span class="comment"> *</span></div>
<div class="line"><a id="l01560" name="l01560"></a><span class="lineno"> 1560</span><span class="comment"> * For example, in STL, `std::ios_base::app` (&quot;append&quot; file mode constant) is used without having to mention a full-on</span></div>
<div class="line"><a id="l01561" name="l01561"></a><span class="lineno"> 1561</span><span class="comment"> * `basic_ostream&lt;char, [...]&gt;` (a/k/a `ostream`) nor any other such basic_ostream&lt;&gt; type.  Note</span></div>
<div class="line"><a id="l01562" name="l01562"></a><span class="lineno"> 1562</span><span class="comment"> * basic_ostream&lt;[...]&gt; inherits from `ios_base`.</span></div>
<div class="line"><a id="l01563" name="l01563"></a><span class="lineno"> 1563</span><span class="comment"> *</span></div>
<div class="line"><a id="l01564" name="l01564"></a><span class="lineno"> 1564</span><span class="comment"> * Composition can also be often used.  However, think of it like this: &quot;Really I want to put the stuff right into</span></div>
<div class="line"><a id="l01565" name="l01565"></a><span class="lineno"> 1565</span><span class="comment"> * C&lt;T&gt;, where it belongs, but then people can&#39;t use it easily without instantiating the template, so I&#39;ll just split</span></div>
<div class="line"><a id="l01566" name="l01566"></a><span class="lineno"> 1566</span><span class="comment"> * it off into a _base class.  I could just put the stuff entirely outside C&lt;T&gt;, but _base is a nicer pattern.&quot; */</span></div>
<div class="line"><a id="l01567" name="l01567"></a><span class="lineno"> 1567</span> </div>
<div class="line"><a id="l01568" name="l01568"></a><span class="lineno"> 1568</span><span class="comment">/* - Avoid: Adding public `static` methods into a class just because &quot;everything should be in a class.&quot; -</span></div>
<div class="line"><a id="l01569" name="l01569"></a><span class="lineno"> 1569</span><span class="comment"> * - Instead: Is it really firmly linked conceptually to class C?  No?  Make it a free function then. -</span></div>
<div class="line"><a id="l01570" name="l01570"></a><span class="lineno"> 1570</span><span class="comment"> *</span></div>
<div class="line"><a id="l01571" name="l01571"></a><span class="lineno"> 1571</span><span class="comment"> * This isn&#39;t a hard rule at all.  For example, factory `static` methods are very common, and that&#39;s fine.</span></div>
<div class="line"><a id="l01572" name="l01572"></a><span class="lineno"> 1572</span><span class="comment"> * But that&#39;s different, because in that case it&#39;s essentially a constructor and *is* firmly linked conceptually to</span></div>
<div class="line"><a id="l01573" name="l01573"></a><span class="lineno"> 1573</span><span class="comment"> * class C.  Plus, then this method can access C&#39;s insides (data members even), and that can be very useful.</span></div>
<div class="line"><a id="l01574" name="l01574"></a><span class="lineno"> 1574</span><span class="comment"> *</span></div>
<div class="line"><a id="l01575" name="l01575"></a><span class="lineno"> 1575</span><span class="comment"> * [Rationale: This isn&#39;t a hard rule at all.  Public `static` methods are common.  However, people tend to use classes</span></div>
<div class="line"><a id="l01576" name="l01576"></a><span class="lineno"> 1576</span><span class="comment"> * as, basically, namespaces that organize groups of public `static` methods.  This seems to be a result of the</span></div>
<div class="line"><a id="l01577" name="l01577"></a><span class="lineno"> 1577</span><span class="comment"> * pre-`namespace` era.  Now, one can just make an actual `namespace` if such grouping is desired.  Use judgment.] */</span></div>
<div class="line"><a id="l01578" name="l01578"></a><span class="lineno"> 1578</span> </div>
<div class="line"><a id="l01579" name="l01579"></a><span class="lineno"> 1579</span><span class="comment">/* - Avoid: Using `friend` to &quot;cheat&quot; an otherwise intentional encapsulation design. -</span></div>
<div class="line"><a id="l01580" name="l01580"></a><span class="lineno"> 1580</span><span class="comment"> * - Instead: Reconsider your design. -</span></div>
<div class="line"><a id="l01581" name="l01581"></a><span class="lineno"> 1581</span><span class="comment"> *</span></div>
<div class="line"><a id="l01582" name="l01582"></a><span class="lineno"> 1582</span><span class="comment"> * This is NOT saying `friend`s shouldn&#39;t be used just because.  There are a few perfectly reasonable `friend` uses;</span></div>
<div class="line"><a id="l01583" name="l01583"></a><span class="lineno"> 1583</span><span class="comment"> * a common one is for binary operators written as free functions (`string operator+(string, string)` and such).</span></div>
<div class="line"><a id="l01584" name="l01584"></a><span class="lineno"> 1584</span><span class="comment"> * I won&#39;t try to enumerate them here.  Just saying: If it feels like you&#39;re using `friend` as an &quot;exception&quot; to an</span></div>
<div class="line"><a id="l01585" name="l01585"></a><span class="lineno"> 1585</span><span class="comment"> * otherwise solid relationship between 2 encapsulating entities, then you might be abusing the existing design which</span></div>
<div class="line"><a id="l01586" name="l01586"></a><span class="lineno"> 1586</span><span class="comment"> * can easily lead to more abuse and a mess over time.  Then, ask yourself if maybe that design can be amended. */</span></div>
<div class="line"><a id="l01587" name="l01587"></a><span class="lineno"> 1587</span> </div>
<div class="line"><a id="l01588" name="l01588"></a><span class="lineno"> 1588</span><span class="preprocessor">#  endif</span></div>
<div class="line"><a id="l01589" name="l01589"></a><span class="lineno"> 1589</span><span class="preprocessor">#endif </span><span class="comment">// !defined(FLOW_DOXYGEN_ONLY)</span></div>
<div class="ttc" id="aclassflow_1_1Function_html"><div class="ttname"><a href="classflow_1_1Function.html">flow::Function</a></div><div class="ttdef"><b>Definition:</b> <a href="common_8hpp_source.html#l00512">common.hpp:512</a></div></div>
<div class="ttc" id="aclassflow_1_1cfg_1_1Option__set_html_acd1ce6e7c258d7486388915d59019880"><div class="ttname"><a href="classflow_1_1cfg_1_1Option__set.html#acd1ce6e7c258d7486388915d59019880">flow::cfg::Option_set::operator&lt;&lt;</a></div><div class="ttdeci">std::ostream &amp; operator&lt;&lt;(std::ostream &amp;os, const Option_set&lt; Value_set &gt; &amp;val)</div><div class="ttdoc">Serializes (briefly) an Option_set to a standard output stream.</div><div class="ttdef"><b>Definition:</b> <a href="option__set_8hpp_source.html#l02154">option_set.hpp:2154</a></div></div>
<div class="ttc" id="alog_8hpp_html_a5daa2b6d16edea74bb8bddc75f7fb801"><div class="ttname"><a href="log_8hpp.html#a5daa2b6d16edea74bb8bddc75f7fb801">FLOW_LOG_WITHOUT_CHECKING</a></div><div class="ttdeci">#define FLOW_LOG_WITHOUT_CHECKING(ARG_sev, ARG_stream_fragment)</div><div class="ttdoc">Identical to FLOW_LOG_WITH_CHECKING() but foregoes the filter (Logger::should_log()) check.</div><div class="ttdef"><b>Definition:</b> <a href="log_8hpp_source.html#l00532">log.hpp:532</a></div></div>
<div class="ttc" id="alog_8hpp_html_a626c7dc4d3b4dc0b32a8aac8624d66bc"><div class="ttname"><a href="log_8hpp.html#a626c7dc4d3b4dc0b32a8aac8624d66bc">FLOW_LOG_WARNING</a></div><div class="ttdeci">#define FLOW_LOG_WARNING(ARG_stream_fragment)</div><div class="ttdoc">Logs a WARNING message into flow::log::Logger *get_logger() with flow::log::Component get_log_compone...</div><div class="ttdef"><b>Definition:</b> <a href="log_8hpp_source.html#l00152">log.hpp:152</a></div></div>
<div class="ttc" id="anamespaceflow_1_1util_html_aad8c8f7335eb892350dc386cb4be397e"><div class="ttname"><a href="namespaceflow_1_1util.html#aad8c8f7335eb892350dc386cb4be397e">flow::util::schedule_task_at</a></div><div class="ttdeci">Scheduled_task_handle schedule_task_at(log::Logger *logger_ptr, const Fine_time_pt &amp;at, bool single_threaded, Task_engine *task_engine, Scheduled_task_handler &amp;&amp;task_body_moved)</div><div class="ttdoc">Identical to schedule_task_from_now() except the time is specified in absolute terms.</div><div class="ttdef"><b>Definition:</b> <a href="sched__task_8hpp_source.html#l00245">sched_task.hpp:245</a></div></div>
<div class="ttc" id="anamespaceflow_html_ae02da22c4a101eaab447511c905e4f32"><div class="ttname"><a href="namespaceflow.html#ae02da22c4a101eaab447511c905e4f32">flow::uint8_t</a></div><div class="ttdeci">unsigned char uint8_t</div><div class="ttdoc">Byte. Best way to represent a byte of binary data. This is 8 bits on all modern systems.</div><div class="ttdef"><b>Definition:</b> <a href="common_8hpp_source.html#l00391">common.hpp:391</a></div></div>
</div><!-- fragment --></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Mar 28 2025 22:55:35 for Flow by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
